datastore.py

__author__ = 'Lukas Leufen'
__date__ = '2019-11-22'


from abc import ABC
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.
    """
    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.
    """
    pass


class EmptyScope(Exception):
    """
    Exception that get raised if given scope is not part of the data store.
    """
    pass


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.
    """
    def __init__(self):
        # empty initialise the data-store variables
        self._store: Dict = {}

    def set(self, name: str, obj: Any, scope: str) -> None:
        """
        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
        """
        pass

    def get(self, name: str, scope: str) -> None:
        """
        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
        """
        pass

    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
        """
        pass

    def search_scope(self, scope: str) -> None:
        """
        Abstract method to search for all object names that are stored for given scope
        :param scope: scope to look for
        :return: search result
        """
        pass

    def list_all_scopes(self) -> None:
        """
        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.
        :return: all names
        """
        pass

    def clear_data_store(self) -> None:
        self._store = {}

    def create_args_dict(self, arg_list: List[str], scope: str = "general") -> Dict:
        args = {}
        for arg in arg_list:
            try:
                args[arg] = self.get(arg, scope)
            except (NameNotFoundInDataStore, NameNotFoundInScope):
                pass
        return args

    def set_args_from_dict(self, arg_dict: Dict, scope: str = "general") -> None:
        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.

    This implementation stores data as
    <variable1>
        <scope1>: value
        <scope2>: value
    <variable2>
        <scope1>: value
        <scope3>: value
    """

    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.
        :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
        """
        # open new variable related store with `name` as key if not existing
        if name not in self._store.keys():
            self._store[name] = {}
        self._store[name][scope] = obj

    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).
        :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]

    def get_default(self, name: str, scope: str, default: Any) -> Any:
        """
        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:
            return self._stride_through_scopes(name, scope)[2]
        except (NameNotFoundInDataStore, NameNotFoundInScope):
            return default

    def _stride_through_scopes(self, name, scope, depth=0):
        if depth <= scope.count("."):
            local_scope = scope.rsplit(".", maxsplit=depth)[0]
            try:
                return name, local_scope, self._store[name][local_scope]
            except KeyError:
                return self._stride_through_scopes(name, scope, depth + 1)
        else:
            occurrences = self.search_name(name)
            if len(occurrences) == 0:
                raise NameNotFoundInDataStore(f"Couldn't find {name} in data store")
            else:
                raise NameNotFoundInScope(f"Couldn't find {name} in scope {scope} . {name} is only defined in "
                                          f"{occurrences}")

    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 [])

    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`.
        :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`)
        """
        if current_scope_only:
            names = []
            for (k, v) in self._store.items():
                if scope in v.keys():
                    names.append(k)
            if len(names) > 0:
                if return_all:
                    return sorted([(name, scope, self._store[name][scope]) for name in names], key=lambda tup: tup[0])
                else:
                    return sorted(names)
            else:
                raise EmptyScope(f"Given scope {scope} is not part of the data store. Available scopes are: "
                                 f"{self.list_all_scopes()}")
        else:
            results = []
            for name in self.list_all_names():
                try:
                    res = self._stride_through_scopes(name, scope)
                    if return_all:
                        results.append(res)
                    else:
                        results.append(res[0])
                except (NameNotFoundInDataStore, NameNotFoundInScope):
                    pass
            if return_all:
                return sorted(results, key=lambda tup: tup[0])
            else:
                return sorted(results)

    def list_all_scopes(self) -> List[str]:
        """
        List all available scopes in data store
        :return: names of all stored objects
        """
        scopes = []
        for v in self._store.values():
            for scope in v.keys():
                if scope not in scopes:
                    scopes.append(scope)
        return sorted(scopes)

    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.

    This implementation stores data as
    <scope1>
        <variable1>: value
        <variable2>: value
    <scope2>
        <variable1>: value
        <variable3>: value
    """

    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.
        :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
        """
        if scope not in self._store.keys():
            self._store[scope] = {}
        self._store[scope][name] = obj

    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).
        :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]

    def get_default(self, name: str, scope: str, default: Any) -> Any:
        """
        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:
            return self._stride_through_scopes(name, scope)[2]
        except (NameNotFoundInDataStore, NameNotFoundInScope):
            return default

    def _stride_through_scopes(self, name, scope, depth=0):
        if depth <= scope.count("."):
            local_scope = scope.rsplit(".", maxsplit=depth)[0]
            try:
                return name, local_scope, self._store[local_scope][name]
            except KeyError:
                return self._stride_through_scopes(name, scope, depth + 1)
        else:
            occurrences = self.search_name(name)
            if len(occurrences) == 0:
                raise NameNotFoundInDataStore(f"Couldn't find {name} in data store")
            else:
                raise NameNotFoundInScope(f"Couldn't find {name} in scope {scope} . {name} is only defined in "
                                          f"{occurrences}")

    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 = []
        for (key, val) in self._store.items():
            if name in val.keys():
                keys.append(key)
        return sorted(keys)

    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`.
        :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`)
        """
        if current_scope_only:
            try:
                if return_all:
                    return [(name, scope, self._store[scope][name]) for name in sorted(self._store[scope].keys())]
                else:
                    return sorted(self._store[scope].keys())
            except KeyError:
                raise EmptyScope(f"Given scope {scope} is not part of the data store. Available scopes are: "
                                 f"{self.list_all_scopes()}")
        else:
            results = []
            for name in self.list_all_names():
                try:
                    res = self._stride_through_scopes(name, scope)
                    if return_all:
                        results.append(res)
                    else:
                        results.append(res[0])
                except (NameNotFoundInDataStore, NameNotFoundInScope):
                    pass
            if return_all:
                return sorted(results, key=lambda tup: tup[0])
            else:
                return sorted(results)

    def list_all_scopes(self) -> List[str]:
        """
        List all available scopes in data store
        :return: names of all stored objects
        """
        return sorted(self._store.keys())

    def list_all_names(self) -> List[str]:
        """
        List all names available in the data store.
        :return: all names
        """
        names = []
        scopes = self.list_all_scopes()
        for scope in scopes:
            for name in self._store[scope].keys():
                if name not in names:
                    names.append(name)
        return sorted(names)