Adds the changes_slots event to the base classes for DataSource and KPICalculator

doc/source/plugin_development.rst

@@ -11,14 +11,29 @@ one of the above pluggable entities and its associated classes.
 To implement a new plugin, you must
 
 - define the entity you want to extend (e.g. ``MyOwnDataSource``) as a derived
-  class of the appropriate class (e.g. BaseDataSource), and reimplement
-  the appropriate methods.
-- Define the model that this DataSource needs, by extending
+  class of the appropriate class (e.g. ``BaseDataSource``), and reimplement
+  the appropriate methods:
+  - ``run()``: where the actual computation takes place, given the
+    configuration options specified in the model (which is received as an
+    argument). It is strongly advised that the ``run()`` method is stateless.
+  - ``slots()``: must return a 2-tuple of tuples. Each tuple contains instances
+    of the ``Slot`` class. Slots are the input and output entities of the
+    data source or KPI calculator. Given that this information depends on the
+    configuration options, ``slots()`` accepts the model and must return the
+    appropriate values according to the model options.
+- Define the model that this ``DataSource`` needs, by extending
   ``BaseDataSourceModel`` and adding, with traits, the appropriate data that
   are required by your data source to perform its task.
+  If a trait change in your model influences the input/output slots, you must
+  make sure that the event ``changes_slots`` is fired as a consequence of
+  those changes. This will notify the UI that the new slots need to be
+  recomputed and presented to the user. Failing to do so will have unexpected
+  consequences.
 - Define the Factory, by reimplementing BaseDataSourceFactory and reimplementing
   its ``create_*`` methods to return the above entities.
 - Define a ``Plugin`` by reimplementing ``BaseExtensionPlugin`` and
   reimplementing its initialization defaults methods to return your factory.
 - add the plugin class in the setup.py entry_point, under the namespace
   ``force.bdss.extensions``
+
+

force_bdss/data_sources/base_data_source_model.py

-from traits.api import ABCHasStrictTraits, Instance, List, String
+from traits.api import ABCHasStrictTraits, Instance, List, String, Event
 
 from force_bdss.core.input_slot_map import InputSlotMap
 from .i_data_source_factory import IDataSourceFactory
@@ -25,6 +25,12 @@ class BaseDataSourceModel(ABCHasStrictTraits):
     #: referenced somewhere else (e.g. the KPICalculators).
     output_slot_names = List(String(), visible=False)
 
+    #: This event claims that a change in the model influences the slots
+    #: (either input or output). It must be triggered every time a specific
+    #: option in your model implies a change in the slots. The UI will detect
+    #: this and adapt the visual entries.
+    changes_slots = Event()
+
     def __init__(self, factory, *args, **kwargs):
         self.factory = factory
         super(BaseDataSourceModel, self).__init__(*args, **kwargs)
@@ -35,3 +41,4 @@ class BaseDataSourceModel(ABCHasStrictTraits):
             x.__getstate__() for x in self.input_slot_maps
         ]
         return state
+

force_bdss/kpi/base_kpi_calculator_model.py

-from traits.api import ABCHasStrictTraits, Instance, List, String
+from traits.api import ABCHasStrictTraits, Instance, List, String, Event
 
 from ..core.input_slot_map import InputSlotMap
 from .i_kpi_calculator_factory import IKPICalculatorFactory
@@ -25,6 +25,12 @@ class BaseKPICalculatorModel(ABCHasStrictTraits):
     #: referenced somewhere else (e.g. the KPICalculators).
     output_slot_names = List(String(), visible=False)
 
+    #: This event claims that a change in the model influences the slots
+    #: (either input or output). It must be triggered every time a specific
+    #: option in your model implies a change in the slots. The UI will detect
+    #: this and adapt the visual entries.
+    changes_slots = Event()
+
     def __init__(self, factory, *args, **kwargs):
         self.factory = factory
         super(BaseKPICalculatorModel, self).__init__(*args, **kwargs)