descripe flow methods, make all low-level xml methods private

Author: amueller

openml/flows/flow.py

@@ -6,6 +6,27 @@
 
 
 class OpenMLFlow(object):
+    """OpenML Flow. Stores machine learning models.
+
+    Parameters
+    ----------
+    model : scikit-learn compatible model
+        The model the flow consists of. The model needs to have fit and predict methods.
+    description : string
+        Description of the flow (free text).
+    creator : string
+        FIXME
+    contributor : string
+        FIXME
+    tag : string
+        FIXME
+    id : int, optional
+        Flow ID. Assigned by the server (fixme shouldn't be here?)
+    uploader : string, optional
+        User uploading the model (fixme shouldn't be here?). Assigned by the server.
+
+
+    """
     def __init__(self, model, id=None, uploader=None,
                  description='Flow generated by run_task', creator=None,
                  contributor=None, tag=None):
@@ -20,7 +41,14 @@ def __init__(self, model, id=None, uploader=None,
                      model.__class__.__name__)
         self.external_version = 'Tsklearn_' + sklearn.__version__
 
-    def generate_flow_xml(self):
+    def _generate_flow_xml(self):
+        """Generate xml representation of self for upload to server.
+
+        Returns
+        -------
+        flow_xml : string
+            Flow represented as XML string.
+        """
         model = self.model
         flow_dict = OrderedDict()
         flow_dict['oml:flow'] = OrderedDict()
@@ -53,18 +81,22 @@ def publish(self):
 
         (optional) file_path is the absolute path to the file that is the flow (eg. a script)
         """
-        xml_description = self.generate_flow_xml()
+        xml_description = self._generate_flow_xml()
         data = {'description': xml_description, 'source': self.source}
         return_code, return_value = _perform_api_call(
             "/flow/", data=data)
         return return_code, return_value
 
-    def ensure_flow_exists(self):
-        """
-        First checks if a flow exists for the given model.
-        If it does, then it will return the corresponding flow id.
-        If it does not, then it will create a flow, and return the flow id
-        of the newly created flow.
+    def _ensure_flow_exists(self):
+        """ Checks if a flow exists for the given model and possibly creates it.
+
+        If the given flow exists on the server, the flow-id will simply
+        be returned. Otherwise it will be uploaded to the server.
+
+        Returns
+        -------
+        flow_id : int
+            Flow id on the server.
         """
         import sklearn
         flow_version = 'Tsklearn_' + sklearn.__version__
@@ -83,9 +115,21 @@ def ensure_flow_exists(self):
 def _check_flow_exists(name, version):
     """Retrieves the flow id of the flow uniquely identified by name+version.
 
-    Returns flow id if such a flow exists,
-    returns -1 if flow does not exists,
-    http://www.openml.org/api_docs/#!/flow/get_flow_exists_name_version
+    Parameter
+    ---------
+    name : string
+        Name of the flow
+    version : string
+        Version information associated with flow.
+
+    Returns
+    -------
+    flow_exist : int
+        Flow id or -1 if the flow doesn't exist.
+
+    Notes
+    -----
+    see http://www.openml.org/api_docs/#!/flow/get_flow_exists_name_version
     """
     if not (type(name) is str and len(name) > 0):
         raise ValueError('Parameter \'name\' should be a non-empty string')

openml/runs/run.py

@@ -119,7 +119,7 @@ def run_task(task, model):
         a dictionary with an 'attributes' and 'data' entry for an arff file
     """
     flow = OpenMLFlow(model=model)
-    flow_id = flow.ensure_flow_exists()
+    flow_id = flow._ensure_flow_exists()
     if(flow_id < 0):
         print("No flow")
         return 0, 2
@@ -196,7 +196,6 @@ def _to_dict(taskid, flow_id, setup_string, parameter_settings, tags):
     description['oml:run'] = OrderedDict()
     description['oml:run']['@xmlns:oml'] = 'http://openml.org/openml'
     description['oml:run']['oml:task_id'] = taskid
-
     description['oml:run']['oml:flow_id'] = flow_id
 
     params = []