From d6a4ae2a35098f9637d53c69c4faba92e8200af1 Mon Sep 17 00:00:00 2001
From: Stefano Borini <sborini@enthought.com>
Date: Thu, 20 Jul 2017 14:45:49 +0100
Subject: [PATCH] Added some documentation
---
force_bdss/data_sources/base_data_source.py | 5 +++++
force_bdss/data_sources/base_data_source_model.py | 9 +++++++++
force_bdss/data_sources/i_data_source_bundle.py | 7 ++++++-
force_bdss/io/workflow_writer.py | 13 +++++++++++++
force_bdss/kpi/base_kpi_calculator_model.py | 9 +++++++++
force_bdss/mco/base_mco_model.py | 12 +++++++++++-
force_bdss/workspecs/workflow.py | 9 +++++++++
7 files changed, 62 insertions(+), 2 deletions(-)
diff --git a/force_bdss/data_sources/base_data_source.py b/force_bdss/data_sources/base_data_source.py
index e8eec36..c700ea8 100644
--- a/force_bdss/data_sources/base_data_source.py
+++ b/force_bdss/data_sources/base_data_source.py
@@ -3,6 +3,11 @@ import six
class BaseDataSource(six.with_metaclass(abc.ABCMeta)):
+ """Base class for the DataSource, any computational engine/retriever
+ for data.
+
+ Inherit from this class for your specific DataSource.
+ """
def __init__(self, bundle, application, model):
self.bundle = bundle
self.application = application
diff --git a/force_bdss/data_sources/base_data_source_model.py b/force_bdss/data_sources/base_data_source_model.py
index 2aa81f2..cc3f30e 100644
--- a/force_bdss/data_sources/base_data_source_model.py
+++ b/force_bdss/data_sources/base_data_source_model.py
@@ -4,6 +4,15 @@ from .i_data_source_bundle import IDataSourceBundle
class BaseDataSourceModel(ABCHasStrictTraits):
+ """Base class for the bundle specific DataSource models.
+ This model will also provide, through traits/traitsui magic the View
+ that will appear in the workflow manager UI.
+
+ In your bundle definition, your bundle-specific model must reimplement
+ this class.
+ """
+ #: A reference to the creating bundle, so that we can
+ #: retrieve it as the originating factory.
bundle = Instance(IDataSourceBundle, visible=False, transient=True)
def __init__(self, bundle, *args, **kwargs):
diff --git a/force_bdss/data_sources/i_data_source_bundle.py b/force_bdss/data_sources/i_data_source_bundle.py
index 146c1e8..5270245 100644
--- a/force_bdss/data_sources/i_data_source_bundle.py
+++ b/force_bdss/data_sources/i_data_source_bundle.py
@@ -10,7 +10,12 @@ class IDataSourceBundle(Interface):
name = String()
def create_data_source(self, application, model):
+ """Factory method.
+ Must return the bundle-specific BaseDataSource instance.
+ """
pass
def create_model(self, model_data=None):
- pass
+ """Factory method.
+ Must return the bundle-specific BaseDataSourceModel instance.
+ """
diff --git a/force_bdss/io/workflow_writer.py b/force_bdss/io/workflow_writer.py
index 129e647..a83d54a 100644
--- a/force_bdss/io/workflow_writer.py
+++ b/force_bdss/io/workflow_writer.py
@@ -3,7 +3,20 @@ from traits.api import HasStrictTraits
class WorkflowWriter(HasStrictTraits):
+ """A Writer for writing the Workflow onto disk.
+ """
def write(self, workflow, f):
+ """Writes the workflow model object to a file f in JSON format.
+
+ Parameters
+ ----------
+ workflow: Workflow
+ The Workflow instance to write to file
+
+ f: File
+ A file object on which to write the workflow, properly serialized
+ into JSON.
+ """
data = {
"version": "1",
"workflow": {}
diff --git a/force_bdss/kpi/base_kpi_calculator_model.py b/force_bdss/kpi/base_kpi_calculator_model.py
index 9838c86..1b254a9 100644
--- a/force_bdss/kpi/base_kpi_calculator_model.py
+++ b/force_bdss/kpi/base_kpi_calculator_model.py
@@ -4,6 +4,15 @@ from .i_kpi_calculator_bundle import IKPICalculatorBundle
class BaseKPICalculatorModel(ABCHasStrictTraits):
+ """Base class for the bundle specific KPI calculator models.
+ This model will also provide, through traits/traitsui magic the View
+ that will appear in the workflow manager UI.
+
+ In your bundle definition, your bundle-specific model must reimplement
+ this class.
+ """
+ #: A reference to the creating bundle, so that we can
+ #: retrieve it as the originating factory.
bundle = Instance(IKPICalculatorBundle, visible=False, transient=True)
def __init__(self, bundle, *args, **kwargs):
diff --git a/force_bdss/mco/base_mco_model.py b/force_bdss/mco/base_mco_model.py
index 00ff4af..e746635 100644
--- a/force_bdss/mco/base_mco_model.py
+++ b/force_bdss/mco/base_mco_model.py
@@ -4,8 +4,18 @@ from .i_multi_criteria_optimizer_bundle import IMultiCriteriaOptimizerBundle
class BaseMCOModel(ABCHasStrictTraits):
+ """Base class for the bundle specific MCO models.
+ This model will also provide, through traits/traitsui magic the View
+ that will appear in the workflow manager UI.
+
+ In your bundle definition, your bundle-specific model must reimplement
+ this class.
+ """
+ #: A reference to the creating bundle, so that we can
+ #: retrieve it as the originating factory.
bundle = Instance(IMultiCriteriaOptimizerBundle,
- visible=False, transient=True)
+ visible=False,
+ transient=True)
def __init__(self, bundle, *args, **kwargs):
self.bundle = bundle
diff --git a/force_bdss/workspecs/workflow.py b/force_bdss/workspecs/workflow.py
index 2796f23..b7963a0 100644
--- a/force_bdss/workspecs/workflow.py
+++ b/force_bdss/workspecs/workflow.py
@@ -6,6 +6,15 @@ from ..mco.base_mco_model import BaseMCOModel
class Workflow(HasStrictTraits):
+ """Model object that represents the Workflow as a whole"""
+ #: Contains the bundle-specific MCO Model object.
+ #: Can be None if no MCO has been specified yet.
multi_criteria_optimizer = Instance(BaseMCOModel, allow_none=True)
+
+ #: Contains the bundle-specific DataSource Model objects.
+ #: The list can be empty
data_sources = List(BaseDataSourceModel)
+
+ #: Contains the bundle-specific KPI Calculator Model objects.
+ #: The list can be empty
kpi_calculators = List(BaseKPICalculatorModel)
--
GitLab