[algorithm] Improved doc and fixed related warnings

beat/backend/python/algorithm.py

@@ -26,7 +26,13 @@
 ###############################################################################
 
 
-"""Validation for algorithms"""
+"""
+=========
+algorithm
+=========
+
+Validation for algorithms
+"""
 
 import os
 import sys
@@ -41,7 +47,7 @@ from . import loader
 from . import utils
 
 
-#----------------------------------------------------------
+# ----------------------------------------------------------
 
 
 class Storage(utils.CodeStorage):
@@ -70,11 +76,11 @@ class Storage(utils.CodeStorage):
         super(Storage, self).__init__(path, language)
 
 
-#----------------------------------------------------------
+# ----------------------------------------------------------
 
 
 class Runner(object):
-    '''A special loader class for algorithms, with specialized methods
+    """A special loader class for algorithms, with specialized methods
 
     Parameters:
 
@@ -91,8 +97,7 @@ class Runner(object):
         translating the exception from the user code. Read the documentation of
         :py:func:`.loader.run` for more details.
 
-    '''
-
+    """
 
     def __init__(self, module, obj_name, algorithm, exc=None):
 
@@ -103,7 +108,7 @@ class Runner(object):
                 type, value, traceback = sys.exc_info()
                 six.reraise(exc, exc(value), traceback)
             else:
-                raise # Just re-raise the user exception
+                raise  # Just re-raise the user exception
 
         self.obj = loader.run(class_, '__new__', exc)
         self.name = module.__name__
@@ -146,7 +151,7 @@ class Runner(object):
                     exc = self.exc or ValueError
                     raise exc(message)
 
-            else: # User has not set a value, use the default
+            else:  # User has not set a value, use the default
                 value = algo_parameters[key]['default']
 
             # In the end, set the value on the dictionary to be returned
@@ -156,7 +161,7 @@ class Runner(object):
 
 
     def setup(self, parameters):
-        '''Sets up the algorithm, only effective on the first call'''
+        """Sets up the algorithm, only effective on the first call"""
 
         # Only effective on the first call
         if self.ready:
@@ -169,7 +174,7 @@ class Runner(object):
 
 
     def prepare(self, data_loaders):
-        '''Let the algorithm process the data on the non-principal channels'''
+        """Let the algorithm process the data on the non-principal channels"""
 
         # Only effective on the first call
         if self.prepared:
@@ -198,7 +203,7 @@ class Runner(object):
 
 
     def process(self, inputs=None, data_loaders=None, outputs=None, output=None):
-        '''Runs through data'''
+        """Runs through data"""
 
         exc = self.exc or RuntimeError
 
@@ -243,11 +248,12 @@ class Runner(object):
 
 
     def __getattr__(self, key):
-        '''Returns an attribute of the algorithm - only called at last resort'''
+        """Returns an attribute of the algorithm - only called at last resort
+        """
         return getattr(self.obj, key)
 
 
-#----------------------------------------------------------
+# ----------------------------------------------------------
 
 
 class Algorithm(object):
@@ -255,8 +261,8 @@ class Algorithm(object):
 
     This class can only parse the meta-parameters of the algorithm (i.e., input
     and output declaration, grouping, synchronization details, parameters and
-    splittability). The actual algorithm is not directly treated by this class -
-    it can, however, provide you with a loader for actually running the
+    splittability). The actual algorithm is not directly treated by this class.
+    It can, however, provide you with a loader for actually running the
     algorithmic code (see :py:meth:`Algorithm.runner`).
 
 
@@ -281,33 +287,34 @@ class Algorithm(object):
 
       name (str): The algorithm name
 
-      dataformats (dict): A dictionary containing all pre-loaded dataformats used
-        by this algorithm. Data format objects will be of type
+      dataformats (dict): A dictionary containing all pre-loaded dataformats
+        used by this algorithm. Data format objects will be of type
         :py:class:`.dataformat.DataFormat`.
 
-      libraries (dict): A mapping object defining other libraries this algorithm
-        needs to load so it can work properly.
+      libraries (dict): A mapping object defining other libraries this
+        algorithm needs to load so it can work properly.
 
       uses (dict): A mapping object defining the required library import name
         (keys) and the full-names (values).
 
-      parameters (dict): A dictionary containing all pre-defined parameters that
-        this algorithm accepts.
+      parameters (dict): A dictionary containing all pre-defined parameters
+        that this algorithm accepts.
 
       splittable (bool): A boolean value that indicates if this algorithm is
         automatically parallelizeable by our backend.
 
       input_map (dict): A dictionary where the key is the input name and the
-        value, its type. All input names (potentially from different groups) are
-        comprised in this dictionary.
+        value, its type. All input names (potentially from different groups)
+        are comprised in this dictionary.
 
       output_map (dict): A dictionary where the key is the output name and the
-        value, its type. All output names (potentially from different groups) are
-        comprised in this dictionary.
+        value, its type. All output names (potentially from different groups)
+        are comprised in this dictionary.
 
-      results (dict): If this algorithm is actually an analyzer (i.e., there are
-        no formal outputs, but results that must be saved by the platform), then
-        this dictionary contains the names and data types of those elements.
+      results (dict): If this algorithm is actually an analyzer (i.e., there
+        are no formal outputs, but results that must be saved by the platform),
+        then this dictionary contains the names and data types of those
+        elements.
 
       groups (dict): A list containing dictionaries with inputs and outputs
         belonging to the same synchronization group.
@@ -385,9 +392,9 @@ class Algorithm(object):
 
                 if dataformat_cache and input['type'] in dataformat_cache: #reuse
                     thisformat = dataformat_cache[input['type']]
-                else: #load it
+                else:  # load it
                     thisformat = dataformat.DataFormat(self.prefix, input['type'])
-                    if dataformat_cache is not None: #update it
+                    if dataformat_cache is not None:  # update it
                         dataformat_cache[input['type']] = thisformat
 
                 self.dataformats[input['type']] = thisformat
@@ -397,9 +404,9 @@ class Algorithm(object):
             for name, output in group['outputs'].items():
                 if output['type'] in self.dataformats: continue
 
-                if dataformat_cache and output['type'] in dataformat_cache: #reuse
+                if dataformat_cache and output['type'] in dataformat_cache:  # reuse
                     thisformat = dataformat_cache[output['type']]
-                else: #load it
+                else:  # load it
                     thisformat = dataformat.DataFormat(self.prefix, output['type'])
                     if dataformat_cache is not None: #update it
                         dataformat_cache[output['type']] = thisformat
@@ -550,8 +557,8 @@ class Algorithm(object):
         """Checks if a given value against a declared parameter
 
         This method checks if the provided user value can be safe-cast to the
-        parameter type as defined on its specification and that it conforms to any
-        parameter-imposed restrictions.
+        parameter type as defined on its specification and that it conforms to
+        any parameter-imposed restrictions.
 
 
         Parameters:
@@ -573,10 +580,9 @@ class Algorithm(object):
             declaration.
 
           ValueError: If the parameter cannot be safe cast into the algorithm's
-            type. Alternatively, a ``ValueError`` may also be raised if a range or
-            choice was specified and the value does not obey those settings
+            type. Alternatively, a ``ValueError`` may also be raised if a range
+            or choice was specified and the value does not obey those settings
             stipulated for the parameter
-
         """
 
         if (self.parameters is None) or (parameter not in self.parameters):