add docs for datastore.py

src/datastore.py

+"""Implementation of experiment's data store."""
+
+__all__ = ['DataStoreByVariable', 'DataStoreByScope', 'NameNotFoundInDataStore', 'NameNotFoundInScope', 'EmptyScope',
+           'AbstractDataStore']
 __author__ = 'Lukas Leufen'
 __date__ = '2019-11-22'
 
-
-from abc import ABC
-from functools import wraps
 import inspect
 import types
+from abc import ABC
+from functools import wraps
 from typing import Any, List, Tuple, Dict
 
 
 class NameNotFoundInDataStore(Exception):
-    """
-    Exception that get raised if given name is not found in the entire data store.
-    """
+    """Exception that get raised if given name is not found in the entire data store."""
+
     pass
 
 
 class NameNotFoundInScope(Exception):
-    """
-    Exception that get raised if given name is not found in the provided scope, but can be found in other scopes.
-    """
+    """Exception that get raised if given name is not found in the provided scope, but can be found in other scopes."""
+
     pass
 
 
 class EmptyScope(Exception):
-    """
-    Exception that get raised if given scope is not part of the data store.
-    """
+    """Exception that get raised if given scope is not part of the data store."""
+
     pass
 
 
 class CorrectScope:
     """
-    This class is used as decorator for all class methods, that have scope in parameters. After decoration, the scope
-    argument is not required on method call anymore. If no scope parameter is given, this decorator automatically adds
-    the default scope=`general` to the arguments. Furthermore, calls like `scope=general.sub` are obsolete, because this
-    decorator adds the prefix `general.` if not provided. Therefore, a call like `scope=sub` will actually become
-    `scope=general.sub` after passing this decorator.
+    This class is used as decorator for all class methods, that have scope in parameters.
+
+    After decoration, the scope argument is not required on method call anymore. If no scope parameter is given, this
+    decorator automatically adds the default scope=`general` to the arguments. Furthermore, calls like
+    `scope=general.sub` are obsolete, because this decorator adds the prefix `general.` if not provided. Therefore, a
+    call like `scope=sub` will actually become `scope=general.sub` after passing this decorator.
     """
 
     def __init__(self, func):
+        """Construct decorator."""
         wraps(func)(self)
 
     def __call__(self, *args, **kwargs):
+        """
+        Call method of decorator.
+
+        Update tuple if scope argument does not start with `general` or slot `scope=general` into args if not provided
+        in neither args nor kwargs.
+        """
         f_arg = inspect.getfullargspec(self.__wrapped__)
         pos_scope = f_arg.args.index("scope")
         if len(args) < (len(f_arg.args) - len(f_arg.defaults or "")):
@@ -53,13 +61,16 @@ class CorrectScope:
         return self.__wrapped__(*args, **kwargs)
 
     def __get__(self, instance, cls):
+        """Create bound method object and supply self argument to the decorated method."""
         return types.MethodType(self, instance)
 
     @staticmethod
     def correct(arg: str):
         """
-        adds leading general prefix
+        Add leading general prefix.
+
         :param arg: string argument of scope to add prefix general if necessary
+
         :return: corrected string
         """
         if not arg.startswith("general"):
@@ -68,13 +79,17 @@ class CorrectScope:
 
     def update_tuple(self, t: Tuple, new: Any, ind: int, update: bool = False):
         """
-        Either updates a entry in given tuple t (<old1>, <old2>, <old3>) --(ind=1)--> (<old1>, <new>, <old3>) or slots
+        Update single entry n given tuple or slot entry into given position.
+
+        Either update a entry in given tuple t (<old1>, <old2>, <old3>) --(ind=1)--> (<old1>, <new>, <old3>) or slot
         entry into given position (<old1>, <old2>, <old3>) --(ind=1,update=True)--> (<old1>, <new>, <old2>, <old3>). In
         the latter case, length of returned tuple is increased by 1 in comparison to given tuple.
+
         :param t: tuple to update
         :param new: new element to add to tuple
         :param ind: position to add or slot in
         :param update: updates entry if true, otherwise slot in (default: False)
+
         :return: updated tuple
         """
         t_new = (*t[:ind], self.correct(new), *t[ind + update:])
@@ -82,19 +97,22 @@ class CorrectScope:
 
 
 class AbstractDataStore(ABC):
-
     """
-    Data store for all settings for the experiment workflow to save experiment parameters for the proceeding run_modules
-    and predefine parameters loaded during the experiment setup phase. The data store is hierarchically structured, so
-    that global settings can be overwritten by local adjustments.
+    Abstract data store for all settings for the experiment workflow.
+
+    Save experiment parameters for the proceeding run_modules and predefine parameters loaded during the experiment
+    setup phase. The data store is hierarchically structured, so that global settings can be overwritten by local
+    adjustments.
     """
+
     def __init__(self):
-        # empty initialise the data-store variables
+        """Initialise by creating empty data store."""
         self._store: Dict = {}
 
     def set(self, name: str, obj: Any, scope: str) -> None:
         """
-        Abstract method to add an object to the data store
+        Abstract method to add an object to the data store.
+
         :param name: Name of object to store
         :param obj: The object itself to be stored
         :param scope: the scope / context of the object, under that the object is valid
@@ -103,7 +121,8 @@ class AbstractDataStore(ABC):
 
     def get(self, name: str, scope: str) -> None:
         """
-        Abstract method to get an object from the data store
+        Abstract method to get an object from the data store.
+
         :param name: Name to look for
         :param scope: scope to search the name for
         :return: the stored object
@@ -113,6 +132,7 @@ class AbstractDataStore(ABC):
     def search_name(self, name: str) -> None:
         """
         Abstract method to search for all occurrences of given `name` in the entire data store.
+
         :param name: Name to look for
         :return: search result
         """
@@ -120,7 +140,8 @@ class AbstractDataStore(ABC):
 
     def search_scope(self, scope: str) -> None:
         """
-        Abstract method to search for all object names that are stored for given scope
+        Abstract method to search for all object names that are stored for given scope.
+
         :param scope: scope to look for
         :return: search result
         """
@@ -128,22 +149,44 @@ class AbstractDataStore(ABC):
 
     def list_all_scopes(self) -> None:
         """
-        Abstract method to list all scopes in data store
+        Abstract method to list all scopes in data store.
+
         :return: all found scopes
         """
         pass
 
     def list_all_names(self) -> None:
         """
-        List all names available in the data store.
+        Abstract method to list all names available in the data store.
+
         :return: all names
         """
         pass
 
     def clear_data_store(self) -> None:
+        """
+        Reset entire data store.
+
+        Warning: This will remove all entries of the data store without any exception.
+        """
         self._store = {}
 
-    def create_args_dict(self, arg_list: List[str], scope: str = "general") -> Dict:
+    @CorrectScope
+    def create_args_dict(self, arg_list: List[str], scope: str) -> Dict:
+        """
+        Create dictionary from given argument list (as keys) and the stored data inside data store (as values).
+
+        Try to load all stored elements for `arg_list` and create an entry in return dictionary for each valid key
+        value pair. Not existing keys from arg_list are skipped. This method works on a single scope only and cannot
+        create a dictionary with values from different scopes. Depending on the implementation of the __get__ method,
+        all superior scopes are included in the parameter search, if no element is found for the given subscope.
+
+        :param arg_list: list with all elements to look for
+        :param scope: the scope to search in
+
+        :return: dictionary with all valid elements from given arg_list as key and the corresponding stored object as
+            value.
+        """
         args = {}
         for arg in arg_list:
             try:
@@ -152,32 +195,49 @@ class AbstractDataStore(ABC):
                 pass
         return args
 
-    def set_args_from_dict(self, arg_dict: Dict, scope: str = "general") -> None:
+    @CorrectScope
+    def set_from_dict(self, arg_dict: Dict, scope: str) -> None:
+        """
+        Store multiple objects from dictionary under same `scope`.
+
+        Each object needs to be parsed as key value pair inside the given dictionary. All new entries are stored under
+        the same scope.
+
+        :param arg_dict: updates for the data store, provided as key value pairs
+        :param scope: scope to store updates
+        """
         for (k, v) in arg_dict.items():
             self.set(k, v, scope)
 
 
 class DataStoreByVariable(AbstractDataStore):
-
     """
-    Data store for all settings for the experiment workflow to save experiment parameters for the proceeding run_modules
-    and predefine parameters loaded during the experiment setup phase. The data store is hierarchically structured, so
-    that global settings can be overwritten by local adjustments.
+    Data store for all settings for the experiment workflow.
+
+    Save experiment parameters for the proceeding run_modules and predefine parameters loaded during the experiment
+    setup phase. The data store is hierarchically structured, so that global settings can be overwritten by local
+    adjustments.
 
     This implementation stores data as
-    <variable1>
-        <scope1>: value
-        <scope2>: value
-    <variable2>
-        <scope1>: value
-        <scope3>: value
+
+    .. code-block::
+
+        <variable1>
+            <scope1>: value
+            <scope2>: value
+        <variable2>
+            <scope1>: value
+            <scope3>: value
+
     """
 
     @CorrectScope
     def set(self, name: str, obj: Any, scope: str) -> None:
         """
-        Store an object `obj` with given `name` under `scope`. In the current implementation, existing entries are
-        overwritten.
+        Store an object `obj` with given `name` under `scope`.
+
+        In the current implementation, existing entries are overwritten.
+
         :param name: Name of object to store
         :param obj: The object itself to be stored
         :param scope: the scope / context of the object, under that the object is valid
@@ -190,12 +250,16 @@ class DataStoreByVariable(AbstractDataStore):
     @CorrectScope
     def get(self, name: str, scope: str) -> Any:
         """
-        Retrieve an object with `name` from `scope`. If no object can be found in the exact scope, take an iterative
-        look on the levels above. Raises a NameNotFoundInDataStore error, if no object with given name can be found in
-        the entire data store. Raises a NameNotFoundInScope error, if the object is in the data store but not in the
-        given scope and its levels above (could be either included in another scope or a more detailed sub-scope).
+        Retrieve an object with `name` from `scope`.
+
+        If no object can be found in the exact scope, take an iterative look on the levels above. Raise a
+        NameNotFoundInDataStore error, if no object with given name can be found in the entire data store. Raise a
+        NameNotFoundInScope error, if the object is in the data store but not in the given scope and its levels above
+        (could be either included in another scope or a more detailed sub-scope).
+
         :param name: Name to look for
         :param scope: scope to search the name for
+
         :return: the stored object
         """
         return self._stride_through_scopes(name, scope)[2]
@@ -203,13 +267,18 @@ class DataStoreByVariable(AbstractDataStore):
     @CorrectScope
     def get_default(self, name: str, scope: str, default: Any) -> Any:
         """
+
+        Retrieve an object with `name` from `scope` and return given default if object wasn't found.
+
         Same functionality like the standard get method. But this method adds a default argument that is returned if no
         data was stored in the data store. Use this function with care, because it will not report any errors and just
         return the given default value. Currently, there is no statement that reports, if the returned value comes from
         the data store or the default value.
+
         :param name: Name to look for
         :param scope: scope to search the name for
         :param default: default value that is return, if no data was found for given name and scope
+
         :return: the stored object or the default value
         """
         try:
@@ -236,7 +305,9 @@ class DataStoreByVariable(AbstractDataStore):
     def search_name(self, name: str) -> List[str]:
         """
         Search for all occurrences of given `name` in the entire data store.
+
         :param name: Name to look for
+
         :return: list with all scopes and sub-scopes containing an object stored as `name`
         """
         return sorted(self._store[name] if name in self._store.keys() else [])
@@ -244,12 +315,16 @@ class DataStoreByVariable(AbstractDataStore):
     @CorrectScope
     def search_scope(self, scope: str, current_scope_only=True, return_all=False) -> List[str or Tuple]:
         """
-        Search for given `scope` and list all object names stored under this scope. To look also for all superior scopes
-        set `current_scope_only=False`. To return the scope and the object's value too, set `return_all=True`.
+        Search for given `scope` and list all object names stored under this scope.
+
+        For an expanded search in all superior scopes, set `current_scope_only=False`. To return the scope and the
+        object's value too, set `return_all=True`.
+
         :param scope: scope to look for
         :param current_scope_only: look only for all names for given scope if true, else search for names from superior
             scopes too.
         :param return_all: return name, definition scope and value if True, else just the name
+
         :return: list with all object names (if `return_all=False`) or list with tuple of object name, object scope and
             object value ordered by name (if `return_all=True`)
         """
@@ -284,7 +359,8 @@ class DataStoreByVariable(AbstractDataStore):
 
     def list_all_scopes(self) -> List[str]:
         """
-        List all available scopes in data store
+        List all available scopes in data store.
+
         :return: names of all stored objects
         """
         scopes = []
@@ -297,32 +373,40 @@ class DataStoreByVariable(AbstractDataStore):
     def list_all_names(self) -> List[str]:
         """
         List all names available in the data store.
+
         :return: all names
         """
         return sorted(self._store.keys())
 
 
 class DataStoreByScope(AbstractDataStore):
-
     """
-    Data store for all settings for the experiment workflow to save experiment parameters for the proceeding run_modules
-    and predefine parameters loaded during the experiment setup phase. The data store is hierarchically structured, so
-    that global settings can be overwritten by local adjustments.
+    Data store for all settings for the experiment workflow.
+
+    Save experiment parameters for the proceeding run_modules and predefine parameters loaded during the experiment
+    setup phase. The data store is hierarchically structured, so that global settings can be overwritten by local
+    adjustments.
 
     This implementation stores data as
-    <scope1>
-        <variable1>: value
-        <variable2>: value
-    <scope2>
-        <variable1>: value
-        <variable3>: value
+
+    .. code-block::
+
+        <scope1>
+            <variable1>: value
+            <variable2>: value
+        <scope2>
+            <variable1>: value
+            <variable3>: value
+
     """
 
     @CorrectScope
     def set(self, name: str, obj: Any, scope: str) -> None:
         """
-        Store an object `obj` with given `name` under `scope`. In the current implementation, existing entries are
-        overwritten.
+        Store an object `obj` with given `name` under `scope`.
+
+        In the current implementation, existing entries are overwritten.
+
         :param name: Name of object to store
         :param obj: The object itself to be stored
         :param scope: the scope / context of the object, under that the object is valid
@@ -334,12 +418,16 @@ class DataStoreByScope(AbstractDataStore):
     @CorrectScope
     def get(self, name: str, scope: str) -> Any:
         """
-        Retrieve an object with `name` from `scope`. If no object can be found in the exact scope, take an iterative
-        look on the levels above. Raises a NameNotFoundInDataStore error, if no object with given name can be found in
-        the entire data store. Raises a NameNotFoundInScope error, if the object is in the data store but not in the
-        given scope and its levels above (could be either included in another scope or a more detailed sub-scope).
+        Retrieve an object with `name` from `scope`.
+
+        If no object can be found in the exact scope, take an iterative look on the levels above. Raise a
+        NameNotFoundInDataStore error, if no object with given name can be found in the entire data store. Raise a
+        NameNotFoundInScope error, if the object is in the data store but not in the given scope and its levels above
+        (could be either included in another scope or a more detailed sub-scope).
+
         :param name: Name to look for
         :param scope: scope to search the name for
+
         :return: the stored object
         """
         return self._stride_through_scopes(name, scope)[2]
@@ -347,13 +435,17 @@ class DataStoreByScope(AbstractDataStore):
     @CorrectScope
     def get_default(self, name: str, scope: str, default: Any) -> Any:
         """
+        Retrieve an object with `name` from `scope` and return given default if object wasn't found.
+
         Same functionality like the standard get method. But this method adds a default argument that is returned if no
         data was stored in the data store. Use this function with care, because it will not report any errors and just
         return the given default value. Currently, there is no statement that reports, if the returned value comes from
         the data store or the default value.
+
         :param name: Name to look for
         :param scope: scope to search the name for
         :param default: default value that is return, if no data was found for given name and scope
+
         :return: the stored object or the default value
         """
         try:
@@ -380,7 +472,9 @@ class DataStoreByScope(AbstractDataStore):
     def search_name(self, name: str) -> List[str]:
         """
         Search for all occurrences of given `name` in the entire data store.
+
         :param name: Name to look for
+
         :return: list with all scopes and sub-scopes containing an object stored as `name`
         """
         keys = []
@@ -392,12 +486,16 @@ class DataStoreByScope(AbstractDataStore):
     @CorrectScope
     def search_scope(self, scope: str, current_scope_only: bool = True, return_all: bool = False) -> List[str or Tuple]:
         """
-        Search for given `scope` and list all object names stored under this scope. To look also for all superior scopes
-        set `current_scope_only=False`. To return the scope and the object's value too, set `return_all=True`.
+        Search for given `scope` and list all object names stored under this scope.
+
+        For an expanded search in all superior scopes, set `current_scope_only=False`. To return the scope and the
+        object's value too, set `return_all=True`.
+
         :param scope: scope to look for
         :param current_scope_only: look only for all names for given scope if true, else search for names from superior
             scopes too.
         :param return_all: return name, definition scope and value if True, else just the name
+
         :return: list with all object names (if `return_all=False`) or list with tuple of object name, object scope and
             object value ordered by name (if `return_all=True`)
         """
@@ -428,7 +526,8 @@ class DataStoreByScope(AbstractDataStore):
 
     def list_all_scopes(self) -> List[str]:
         """
-        List all available scopes in data store
+        List all available scopes in data store.
+
         :return: names of all stored objects
         """
         return sorted(self._store.keys())
@@ -436,6 +535,7 @@ class DataStoreByScope(AbstractDataStore):
     def list_all_names(self) -> List[str]:
         """
         List all names available in the data store.
+
         :return: all names
         """
         names = []