Documentation and tests

force_bdss/data_sources/base_data_source_bundle.py

@@ -6,22 +6,51 @@ from .i_data_source_bundle import IDataSourceBundle
 
 @provides(IDataSourceBundle)
 class BaseDataSourceBundle(ABCHasStrictTraits):
+    """Base class for DataSource bundles. Reimplement this class to
+    create your own DataSource.
+    """
+    # NOTE: changes to this class must be ported also to the IDataSourceBundle
+
     #: Unique identifier that identifies the bundle uniquely in the
     #: universe of bundles. Create one with the function bundle_id()
     id = String()
 
-    #: A human readable name of the bundle
+    #: A human readable name of the bundle. Spaces allowed
     name = String()
 
     @abc.abstractmethod
     def create_data_source(self, application, model):
         """Factory method.
         Must return the bundle-specific BaseDataSource instance.
+
+        Parameters
+        ----------
+        application: Application
+            The envisage application.
+        model: BaseDataSourceModel
+            The model of the data source, instantiated with create_model()
+
+        Returns
+        -------
+        BaseDataSource
+            The specific instance of the generated DataSource
         """
-        pass
 
     @abc.abstractmethod
     def create_model(self, model_data=None):
         """Factory method.
-        Must return the bundle-specific BaseDataSourceModel instance.
+        Creates the model object (or network of model objects) of the KPI
+        calculator. The model can provide a traits UI View according to
+        traitsui specifications, so that a UI can be provided automatically.
+
+        Parameters
+        ----------
+        model_data: dict or None
+            A dictionary containing the information to recreate the model.
+            If None, an empty (with defaults) model will be returned.
+
+        Returns
+        -------
+        BaseDataSourceModel
+            The model
         """

force_bdss/data_sources/i_data_source_bundle.py

@@ -13,7 +13,6 @@ class IDataSourceBundle(Interface):
         """Factory method.
         Must return the bundle-specific BaseDataSource instance.
         """
-        pass
 
     def create_model(self, model_data=None):
         """Factory method.

force_bdss/data_sources/tests/test_base_data_source_bundle.py

+import unittest
+
+from force_bdss.data_sources.base_data_source_bundle import \
+    BaseDataSourceBundle
+
+
+class DummyDataSourceBundle(BaseDataSourceBundle):
+    id = "foo"
+
+    name = "bar"
+
+    def create_data_source(self, application, model):
+        pass
+
+    def create_model(self, model_data=None):
+        pass
+
+
+class TestBaseDataSourceBundle(unittest.TestCase):
+    def test_initialization(self):
+        bundle = DummyDataSourceBundle()
+        self.assertEqual(bundle.id, 'foo')
+        self.assertEqual(bundle.name, 'bar')

force_bdss/kpi/base_kpi_calculator_bundle.py

@@ -6,14 +6,53 @@ from .i_kpi_calculator_bundle import IKPICalculatorBundle
 
 @provides(IKPICalculatorBundle)
 class BaseKPICalculatorBundle(ABCHasStrictTraits):
+    """Base class for the Key Performance Indicator calculator bundles.
+    Inherit from this class to create a bundle, and reimplement the abstract
+    methods.
+    """
+    # NOTE: any changes in this interface must be ported to
+    # IKPICalculatorBundle
+
+    #: A unique ID generated with bundle_id() routine
     id = String()
 
+    #: A UI friendly name for the bundle. Can contain spaces.
     name = String()
 
     @abc.abstractmethod
     def create_kpi_calculator(self, application, model):
-        pass
+        """Factory method.
+        Creates and returns an instance of a KPI Calculator, associated
+        to the given application and model.
+
+        Parameters
+        ----------
+        application: Application
+            The envisage application.
+        model: BaseKPICalculatorModel
+            The model of the calculator, instantiated with create_model()
+
+        Returns
+        -------
+        BaseKPICalculator
+            The specific instance of the generated KPICalculator
+        """
 
     @abc.abstractmethod
     def create_model(self, model_data=None):
-        pass
+        """Factory method.
+        Creates the model object (or network of model objects) of the KPI
+        calculator. The model can provide a traits UI View according to
+        traitsui specifications, so that a UI can be provided automatically.
+
+        Parameters
+        ----------
+        model_data: dict or None
+            A dictionary containing the information to recreate the model.
+            If None, an empty (with defaults) model will be returned.
+
+        Returns
+        -------
+        BaseKPICalculatorModel
+            The model
+        """

force_bdss/kpi/i_kpi_calculator_bundle.py

@@ -2,6 +2,8 @@ from traits.api import Interface, String
 
 
 class IKPICalculatorBundle(Interface):
+    """Envisage required interface for the BaseKPICalculatorBundle.
+    You should not need to use this directly."""
     id = String()
 
     name = String()

force_bdss/kpi/tests/test_base_kpi_calculator_bundle.py

+import unittest
+
+from force_bdss.kpi.base_kpi_calculator_bundle import \
+    BaseKPICalculatorBundle
+
+
+class DummyKPICalculatorBundle(BaseKPICalculatorBundle):
+    id = "foo"
+
+    name = "bar"
+
+    def create_kpi_calculator(self, application, model):
+        pass
+
+    def create_model(self, model_data=None):
+        pass
+
+
+class TestBaseKPICalculatorBundle(unittest.TestCase):
+    def test_initialization(self):
+        bundle = DummyKPICalculatorBundle()
+        self.assertEqual(bundle.id, 'foo')
+        self.assertEqual(bundle.name, 'bar')

force_bdss/mco/base_multi_criteria_optimizer_bundle.py

@@ -10,18 +10,67 @@ from force_bdss.mco.i_multi_criteria_optimizer_bundle import (
 
 @provides(IMultiCriteriaOptimizerBundle)
 class BaseMultiCriteriaOptimizerBundle(ABCHasStrictTraits):
+    """Base class for the MultiCriteria Optimizer bundle.
+    """
+    # NOTE: any changes to the interface of this class must be replicated
+    # in the IMultiCriteriaOptimizerBundle interface class.
+
+    #: A unique ID produced with the bundle_id() routine.
     id = String()
 
+    #: A user friendly name of the bundle. Spaces allowed.
     name = String()
 
     @abc.abstractmethod
     def create_optimizer(self, application, model):
-        pass
+        """Factory method.
+        Creates the optimizer with the given application
+        and model and returns it to the caller.
+
+        Parameters
+        ----------
+        application: Application
+            The envisage application instance
+        model: BaseMCOModel
+            The model to associate to the optimizer, instantiated through
+            create_model()
+
+        Returns
+        -------
+        BaseMCOOptimizer
+            The optimizer
+        """
 
     @abc.abstractmethod
     def create_model(self, model_data=None):
-        pass
+        """Factory method.
+        Creates the model object (or network of model objects) of the MCO.
+        The model can provide a traits UI View according to traitsui
+        specifications, so that a UI can be provided automatically.
+
+        Parameters
+        ----------
+        model_data: dict or None
+            A dictionary of data that can be interpreted appropriately to
+            recreate the model. If None, an empty (with defaults) model will
+            be created and returned.
+
+        Returns
+        -------
+        BaseMCOModel
+            The MCOModel
+        """
 
     @abc.abstractmethod
-    def create_communicator(self, model_data):
-        pass
+    def create_communicator(self, application, model):
+        """Factory method. Returns the communicator class that allows
+        exchange between the MCO and the evaluator code.
+
+        Parameters
+        ----------
+        application: Application
+            The envisage application instance
+        model: BaseMCOModel
+            The model to associate to the optimizer, instantiated through
+            create_model()
+        """

force_bdss/mco/i_multi_criteria_optimizer_bundle.py

@@ -2,6 +2,9 @@ from traits.api import Interface, String
 
 
 class IMultiCriteriaOptimizerBundle(Interface):
+    """Interface for the MultiCriteria Optimizer bundle.
+    You should not need it, as its main use is for envisage support.
+    """
     id = String()
 
     name = String()
@@ -12,5 +15,5 @@ class IMultiCriteriaOptimizerBundle(Interface):
     def create_model(self, model_data=None):
         pass
 
-    def create_communicator(self, model_data):
+    def create_communicator(self, application, model):
         pass

force_bdss/mco/tests/test_base_multi_criteria_optimizer_bundle.py

+import unittest
+
+from force_bdss.mco.base_multi_criteria_optimizer_bundle import (
+    BaseMultiCriteriaOptimizerBundle
+)
+
+
+class DummyMCOBundle(BaseMultiCriteriaOptimizerBundle):
+    id = "foo"
+
+    name = "bar"
+
+    def create_optimizer(self, application, model):
+        pass
+
+    def create_model(self, model_data=None):
+        pass
+
+    def create_communicator(self, model_data):
+        pass
+
+
+class TestBaseDataSourceBundle(unittest.TestCase):
+    def test_initialization(self):
+        bundle = DummyMCOBundle()
+        self.assertEqual(bundle.id, 'foo')
+        self.assertEqual(bundle.name, 'bar')