apytizer 0.0.1a0__py3-none-any.whl → 0.0.1b1__py3-none-any.whl

apytizer/states/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/states/__init__.py
+
+# Local Imports
+from .abstract_state import *
+from .local_state import *

apytizer/states/abstract_state.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/states/abstract_state.py
+"""Abstract State Class Interface.
+
+This module defines an abstract state class which provides an interface
+for subclasses to implement.
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+import abc
+from typing import Any
+from typing import Generator
+from typing import Mapping
+from typing import Optional
+
+__all__ = ["AbstractState"]
+
+
+class AbstractState(abc.ABC):
+    """Represents an abstract state."""
+
+    @abc.abstractmethod
+    def __contains__(self, key: str) -> bool:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __eq__(self, other: object) -> bool:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __getitem__(self, key: str) -> Any:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __setitem__(self, key: str, value: Any) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __iter__(self) -> Generator[Any, None, None]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get(self, key: str) -> Any:
+        """Abstract method for getting an item from state."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def items(self) -> Any:
+        """Abstract method for getting items from state."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def update(
+        self,
+        __m: Optional[Mapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Abstract method for updating state."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def rollback(self) -> None:
+        """Abstract method for rolling back changes to state."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def save(self) -> None:
+        """Abstract method for saving changes to state."""
+        raise NotImplementedError

apytizer/states/local_state.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/states/base_state.py
+"""Base State Class.
+
+This module defines the implementation of a base state class.
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+import collections
+from typing import Any
+from typing import Dict
+from typing import Generator
+from typing import Mapping
+from typing import Optional
+from typing import Tuple
+
+# Local Imports
+from . import AbstractState
+from .. import utils
+
+__all__ = ["LocalState"]
+
+
+class LocalState(AbstractState):
+    """Class implements a local state."""
+
+    def __init__(
+        self,
+        base: Optional[Dict[str, Any]] = None,
+        default: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self._state = collections.ChainMap(base or {}, default or {})
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._state
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            dict(other) == dict(self)
+            if isinstance(other, AbstractState)
+            else False
+        )
+
+    def __getitem__(self, key: str) -> Any:
+        result = self.get(key)
+        return result
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self._state = utils.deep_set(self._state, key, value)
+
+    def __iter__(self) -> Generator[Tuple[str, Any], None, None]:
+        yield from self._state.items()
+
+    def get(self, key: str) -> Any:
+        """Get an item from state.
+
+        Args:
+            key: Key.
+
+        Returns:
+            Value of key in state.
+
+        """
+        if not isinstance(key, str):  # type: ignore
+            message = f"expected type 'str', got {type(key)} instead"
+            raise TypeError(message)
+
+        result = utils.deep_get(self._state, key)
+        return result
+
+    def items(self) -> Any:
+        """Get items from state."""
+        results = self._state.items()
+        return results
+
+    def update(
+        self,
+        __m: Optional[Mapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Update state.
+
+        Args:
+            __m (optional): Mapping. Default ``None``.
+            **kwargs: Keyword arguments.
+
+        """
+        self._state.update(__m or {}, **kwargs)
+
+    def rollback(self) -> None:
+        """Roll back changes to state."""
+        self._state.clear()
+
+    def save(self) -> None:
+        """Save changes to state."""
+        if self._state.maps[0]:  # type: ignore
+            self._state = self._state.new_child()  # type: ignore

apytizer/utils/__init__.py

@@ -1,6 +1,11 @@
 # -*- coding: utf-8 -*-
+# src/apytizer/utils/__init__.py
 
-# pylint: skip-file
-
-from .generate_key import generate_key
-from .merge import merge
+# Local Imports
+from .caching import *
+from .dictionaries import *
+from .errors import *
+from .iterables import *
+from .objects import *
+from .strings import *
+from .typing import *

apytizer/utils/caching.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+
+# Standard Library Import
+from typing import Any
+from typing import Callable
+from typing import Hashable
+from typing import Tuple
+
+# Third-Party Imports
+from cachetools.keys import hashkey
+
+__all__ = ["generate_key"]
+
+
+def generate_key(*tags: str) -> Callable[..., Tuple[Hashable, ...]]:
+    """Generates a hashable key for caching values.
+
+    Args:
+        *tags: Tags.
+
+    """
+
+    def hash_parameters(*args: Any, **kwargs: Any) -> Tuple[Hashable, ...]:
+        """Hashes function parameters.
+
+        Args:
+            *args: Positional arguments.
+            **kwargs: Keyword arguments.
+
+        Return:
+            Cache Key.
+
+        """
+        result = hashkey(
+            *tags, *args, *[f"{k!s}={v!s}" for k, v in sorted(kwargs.items())]
+        )
+        return result
+
+    return hash_parameters

apytizer/utils/dictionaries.py

@@ -0,0 +1,375 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/utils/dictionaries.py
+
+# Standard Library Imports
+from collections import ChainMap
+import functools
+from typing import Any
+from typing import Collection
+from typing import Dict
+from typing import Hashable
+from typing import List
+from typing import Optional
+from typing import Set
+from typing import TypeVar
+from typing import Union
+
+# Local Imports
+from .errors import raise_for_instance
+from .typing import allinstance
+
+__all__ = [
+    "deep_get",
+    "deep_set",
+    "iter_get",
+    "iter_set",
+    "omit",
+    "pick",
+    "merge",
+    "remap_keys",
+    "remove_nulls",
+]
+
+# Custom types:
+T = TypeVar("T")
+
+
+def deep_get(
+    __d: Dict[Hashable, Any],
+    /,
+    keys: str,
+    default: Optional[object] = None,
+) -> Any:
+    """Get value from nested dictionary object.
+
+    Args:
+        __d: Dictionary object.
+        keys: String of keys seperated by periods.
+        default (optional): Default if value not found. Default ``None``.
+
+    Returns:
+        Value of key in nested dictionary object.
+
+    Raises:
+        TypeError: when argument is not an instance of 'dict'.
+
+    """
+
+    def _get(data: Dict[str, Any], key: str) -> Any:
+        """Get value of key from dictionary.
+
+        Args:
+            data: Dictionary object.
+            key: Key for which to get value.
+
+        Returns:
+            Value.
+
+        """
+        try:
+            result = data.get(key, default)
+        except AttributeError:  # if data is `None`
+            return default
+        else:
+            return result
+
+    raise_for_instance(__d, (dict, ChainMap))
+    raise_for_instance(keys, str)
+
+    value = functools.reduce(_get, keys.split("."), __d)
+    return value
+
+
+def deep_set(
+    __d: Dict[Hashable, Any],
+    /,
+    keys: Union[List[str], str],
+    value: Any,
+) -> Dict[Hashable, Any]:
+    """Sets key to value in nested dictionary object.
+
+    Args:
+        __d: Dictionary object.
+        keys: Either list of keys, or string of keys seperated by periods.
+        value: Value to set for key.
+
+    Returns:
+        Updated dictionary object.
+
+    Raises:
+        TypeError: when argument is not an instance of 'dict'.
+
+    """
+    raise_for_instance(__d, (dict, ChainMap))
+
+    if isinstance(keys, str):
+        keys = keys.split(".")
+
+    try:
+        key, remaining = keys[0], keys[1:]
+        __d[key] = (
+            deep_set(__d.get(key) or {}, remaining, value)
+            if len(remaining) >= 1
+            else value
+        )
+    except KeyError as error:
+        raise KeyError(f"{key}.{error.args[0]}") from error  # type: ignore
+
+    except (IndexError, TypeError) as error:
+        raise KeyError(keys[0]) from error
+
+    return __d
+
+
+def iter_get(
+    __iter: List[Dict[Hashable, Any]],
+    /,
+    key: str,
+) -> List[object]:
+    """Get value for key from each dictionary in an iterable object.
+
+    Args:
+        __iter: Iterable object containing dictionaries.
+        key: Key for which to retrieve value.
+
+    Raises:
+        TypeError: when argument is not an iterable object.
+        ValueError: when not all items are dictionaries.
+
+    """
+    raise_for_instance(__iter, list)
+
+    if not allinstance(__iter, dict):
+        raise ValueError("iterable object must contain dictionaries")
+
+    results = [deep_get(item, key) for item in __iter]
+    return results
+
+
+def iter_set(
+    __iter: List[Dict[Hashable, Any]],
+    /,
+    key: str,
+    value: Any,
+) -> List[Dict[Hashable, Any]]:
+    """Set value of key on each dictionary in an iterable object.
+
+    Args:
+        __iter: Iterable object containing dictionaries.
+        key: Key for which to set value.
+        value: Value to set.
+
+    Returns:
+        List of updated dictionary objects.
+
+    Raises:
+        TypeError: when argument is not an iterable object.
+        ValueError: when not all items are dictionaries.
+
+    """
+    raise_for_instance(__iter, list)
+
+    if not allinstance(__iter, dict):
+        raise ValueError("iterable object must contain dictionaries")
+
+    results = [deep_set(item, key, value) for item in __iter]
+    return results
+
+
+def merge(
+    *args: Optional[Dict[Hashable, T]],
+    overwrite: bool = True,
+) -> Optional[Dict[Hashable, T]]:
+    """Combines dictionary objects into a single dictionary.
+
+    Args:
+        *args: Dictionary objects to merge.
+        overwrite (optional): Overwrite existing keys. Default ``True``.
+
+    Returns:
+        Merged dictionary.
+
+    Raises:
+        TypeError: when arguments are not all dictionaries.
+        ValueError: when keys conflict and overwrite is ``False``.
+
+    """
+    if not allinstance(args, (dict, type(None))):
+        raise TypeError("all arguments must be instances of 'dict'")
+
+    def _merge_dictionaries(
+        first: Dict[Hashable, Any],
+        second: Dict[Hashable, Any],
+        /,
+        path: Optional[List[str]] = None,
+        overwrite: bool = False,
+    ) -> Dict[Hashable, Any]:
+        """Merge two dictionaries.
+
+        Args:
+            first: First dictionary.
+            second: Second dictionary.
+            path: Path of keys in nested dictionary.
+            overwrite (optional): Overwrite existing keys. Default ``False``.
+
+        Raises:
+            ValueError: when keys conflict and overwrite is ``False``.
+
+        .. _Based On:
+            https://stackoverflow.com/questions/7204805/how-to-merge-dictionaries-of-dictionaries.
+
+        """
+        __path: List[str] = [] if path is None else path
+
+        for key in second:
+            if key in first:
+                if allinstance((first[key], second[key]), dict):
+                    first[key] = _merge_dictionaries(
+                        first[key],
+                        second[key],
+                        path=[*__path, str(key)],
+                        overwrite=overwrite,
+                    )
+
+                elif allinstance((first[key], second[key]), list):
+                    first[key] = _merge_lists(first[key], second[key])
+
+                elif allinstance((first[key], second[key]), set):
+                    first[key] = _merge_sets(first[key], second[key])
+
+                elif overwrite is True:
+                    first[key] = second[key]
+
+                else:
+                    location = ".".join(k for k in [*__path, str(key)] if k)
+                    message = f"Conflict at {location!s}"
+                    raise ValueError(message)
+
+            else:
+                first[key] = second[key]
+
+        return first
+
+    def _merge_lists(first: List[Any], second: List[Any]) -> List[Any]:
+        return [*first, *second]
+
+    def _merge_sets(first: Set[Any], second: Set[Any]) -> Set[Any]:
+        return first.union(second)
+
+    func = functools.partial(_merge_dictionaries, overwrite=overwrite)
+    result: Dict[Hashable, Any] = functools.reduce(
+        lambda acc, cur: func(acc, cur) if cur else acc, args, {}
+    )
+    return result if result else None
+
+
+def omit(
+    __d: Dict[Hashable, Any],
+    /,
+    keys: Collection[str],
+) -> Dict[Hashable, Any]:
+    """Omit multiple key-value pairs from dictionary.
+
+    Args:
+        __d: Dictionary object.
+        keys: Collection of keys.
+
+    Returns:
+        Dictionary without the selected key-value pairs.
+
+    Raises:
+        TypeError: when argument is not an instance of 'dict'.
+
+    """
+    raise_for_instance(__d, dict)
+
+    # TODO: Add support for omitting key-value pairs from nested dictionaries.
+    results: Dict[Hashable, Any] = {k: __d[k] for k in __d if k not in keys}
+    return results
+
+
+def pick(
+    __d: Dict[Hashable, Any],
+    /,
+    keys: Collection[str],
+) -> Dict[Hashable, Any]:
+    """Pick multiple values from a dictionary.
+
+    Args:
+        __d: Dictionary object.
+        keys: Collection of keys.
+
+    Returns:
+        Dictionary containing the selected key-value pairs.
+
+    Raises:
+        TypeError: when argument is not an instance of 'dict'.
+
+    """
+    raise_for_instance(__d, (dict, ChainMap))
+
+    def _last(key: str) -> Hashable:
+        return key.split(".")[-1]
+
+    results = {_last(key): deep_get(__d, key) for key in keys}
+    return results
+
+
+def remap_keys(
+    __d: Dict[Hashable, Any],
+    /,
+    key_map: Dict[Hashable, str],
+    remove: bool = False,
+) -> Dict[Hashable, Any]:
+    """Remap dictionary object to new keys.
+
+    Args:
+        __d: Dictionary object for which keys will be remapped.
+        key_map: Dictionary mapping old keys to new ones.
+        remove (optional): Whether to drop key-value pairs if key is not found
+            in key map. Default ``False``.
+
+    Returns:
+        Remapped dictionary.
+
+    Raises:
+        TypeError: when argument is not an instance of 'dict'.
+
+    """
+    raise_for_instance(__d, dict)
+
+    result: Dict[Hashable, Any] = {
+        key_map.get(key, key): value
+        for key, value in __d.items()
+        if key in key_map or remove is False
+    }
+    return result
+
+
+def remove_nulls(
+    __d: Dict[Hashable, Any],
+    /,
+    null_values: Optional[Collection[Any]] = None,
+) -> Dict[Hashable, Any]:
+    """Remove all null values from dictionary.
+
+    Args:
+        __d: Dictionary from which to remove null values.
+        null_values (optional): Additional values to recognize as null.
+
+    Returns:
+        Dictionary without null values.
+
+    Raises:
+        TypeError: when argument is not an instance of 'dict'.
+
+    """
+    raise_for_instance(__d, dict)
+
+    nulls = null_values or []
+    result: Dict[Hashable, Any] = {
+        key: value
+        for key, value in __d.items()
+        if value is not None and value not in nulls
+    }
+    return result

apytizer/utils/errors.py

@@ -0,0 +1,104 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/utils/errors.py
+
+# Standard Library Imports
+from typing import Any
+from typing import Tuple
+from typing import Union
+
+# Local Imports
+from .. import utils
+
+__all__ = [
+    "raise_for_attribute",
+    "raise_for_instance",
+    "raise_for_none",
+]
+
+
+def raise_for_attribute(__obj: object, __attr: str, /) -> None:
+    """Raise error if object does not contain expected attribute.
+
+    Args:
+        __obj: Object to check for attribute.
+        __attr: Attribute for which to check.
+
+    """
+    if not hasattr(__obj, __attr):
+        cls = __obj.__class__.__name__
+        message = f"type object '{cls!s}' has no attribute '{__attr!s}'"
+        raise AttributeError(message)
+
+
+def raise_for_instance(
+    __value: object,
+    __expected: Union[type, Tuple[Union[type, Tuple[Any, ...]], ...]],
+    /,
+) -> None:
+    """Raise error if value is not an instance of expected type.
+
+    Args:
+        __value: Object to check for type.
+        __expected: Expected type(s).
+
+    """
+    correct_type = isinstance(__value, __expected)
+
+    if not correct_type and isinstance(__expected, tuple):
+        _raise_for_multiple_types(__value, __expected)
+
+    if not correct_type and not isinstance(__expected, tuple):
+        _raise_for_single_type(__value, __expected)
+
+
+def _raise_for_multiple_types(
+    __value: object, __types: Tuple[Union[type, Tuple[Any, ...]], ...], /
+) -> None:
+    """Raise error if value is not among expected types.
+
+    Args:
+        __value: Object to check for type.
+        __types: Expected types.
+
+    """
+    type_names = utils.iter_getattr(__types, "__name__")
+    formatted_names = utils.iter_format(type_names, "'{}'")
+    expected = utils.syntactic_list(formatted_names, "or")
+    actual = type(__value).__name__
+
+    message = f"expected types {expected!s}, got {actual!s} instead"
+    raise TypeError(message)
+
+
+def _raise_for_single_type(__value: object, __type: type, /) -> None:
+    """Raise error if value is not an instance of expected type.
+
+    Args:
+        __value: Object to check for type.
+        __type: Expected type.
+
+    """
+    expected, actual = f"'{__type.__name__}'", type(__value).__name__
+    message = f"expected type {expected!s}, got {actual!s} instead"
+    raise TypeError(message)
+
+
+def raise_for_none(*args: Any, **kwargs: Any) -> None:
+    """Raise error if value is None.
+
+    Args:
+        *args: Positional arguments.
+        **kwargs: Keyword arguments.
+
+    Raises:
+        ValueError: when any argument is ``None``.
+
+    """
+    if any(arg is None for arg in args):
+        message = "argument cannot be 'None'"
+        raise ValueError(message)
+
+    for name, value in kwargs.items():
+        if value is None:
+            message = f"{name} cannot be 'None'"
+            raise ValueError(message)