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

apytizer/utils/dictionaries.py

@@ -0,0 +1,376 @@
+# -*- 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:
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+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[K, V]],
+    overwrite: bool = True,
+) -> Optional[Dict[K, V]]:
+    """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[Any, Any],
+        second: Dict[Any, Any],
+        /,
+        path: Optional[List[str]] = None,
+        overwrite: bool = False,
+    ) -> Dict[Any, 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[Any, 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)

apytizer/utils/iterables.py

@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/utils/iterables.py
+
+# Standard Library Imports
+from typing import Any
+from typing import List
+from typing import SupportsIndex
+
+# Local Imports
+from .typing import allinstance
+
+__all__ = ["deep_append", "deep_extend", "split_list"]
+
+
+def deep_append(
+    __obj: List[List[Any]], __index: SupportsIndex, __item: Any, /
+) -> List[List[Any]]:
+    """Appends value to a list within an iterable object.
+
+    Args:
+        __obj: Iterable object.
+        __index: Index at which to append item.
+        __item: Item to append to nested list.
+
+    Returns:
+        Updated iterable object.
+
+    Raises:
+        TypeError: when argument does not support indexing.
+
+    """
+    if not isinstance(__obj, list):  # type: ignore
+        message = f"expected type 'list', got {type(__obj)} instead"
+        raise TypeError(message)
+
+    if not allinstance(__obj, list):
+        raise ValueError("must contain only lists")
+
+    target: List[Any] = __obj[__index]
+    target.append(__item)
+    return __obj
+
+
+def deep_extend(
+    __obj: List[List[Any]],
+    __index: SupportsIndex,
+    __items: List[Any],
+    /,
+) -> List[List[Any]]:
+    """Extends list within nested iterable object with provided values.
+
+    Args:
+        __obj: Iterable object.
+        __index: Index at which to extend list.
+        __items: Items with which to extend nested list.
+
+    Returns:
+        Updated iterable object.
+
+    Raises:
+        TypeError: when argument does not support indexing.
+
+    """
+    if not isinstance(__obj, list):  # type: ignore
+        message = f"expected type 'list', got {type(__obj)} instead"
+        raise TypeError(message)
+
+    if not allinstance(__obj, list):
+        raise ValueError("iterable object must contain only lists")
+
+    target: List[Any] = __obj[__index]
+    target.extend(__items)
+    return __obj
+
+
+def split_list(__lst: List[Any], /, size: int) -> List[List[Any]]:
+    """Split list into multiple groups of the same size.
+
+    Args:
+        __lst: List to split into groups.
+        size: Maximum size of each group.
+
+    Returns:
+        Groups.
+
+    .. _Based On:
+        https://stackoverflow.com/questions/2231663/slicing-a-list-into-a-list-of-sub-lists
+
+    """
+    results = [__lst[i : i + size] for i in range(0, len(__lst), size)]
+    return results

apytizer/utils/objects.py

@@ -0,0 +1,145 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/utils/objects.py
+
+# Standard Library Imports
+import collections
+import functools
+from typing import Any
+from typing import Iterable
+from typing import List
+from typing import Optional
+
+# Local Imports
+from .typing import allinstance
+
+__all__ = [
+    "deep_getattr",
+    "deep_setattr",
+    "getattrs",
+    "setattrs",
+    "iter_getattr",
+    "iter_setattr",
+]
+
+
+def deep_getattr(__o: object, __name: Iterable[str], /) -> Any:
+    """Get value of attribute in nested object.
+
+    Args:
+        __o: Object on which to get attribute.
+        __name: Name of attribute from which to get value.
+
+    Returns:
+        Value of attribute in nested object.
+
+    """
+    if not isinstance(__name, Iterable):  # type: ignore
+        message = f"'{type(__name)}' object is not iterable"
+        raise TypeError(message)
+
+    attrs = __name.split(".") if isinstance(__name, str) else __name
+    result = functools.reduce(lambda acc, cur: getattr(acc, cur), attrs, __o)
+    return result
+
+
+def deep_setattr(__o: object, __name: str, __value: Any, /) -> None:
+    """Sets attribute to value in nested object.
+
+    Args:
+        __o: Object on which to set attributes.
+        __name: Name of attribute to set on object.
+        __value: Value to set attribute on object.
+
+    Returns:
+        Updated object.
+
+    """
+    attrs = collections.deque(__name.split("."))
+    target = attrs.pop()
+
+    obj = functools.reduce(lambda acc, cur: getattr(acc, cur), attrs, __o)
+    setattr(obj, target, __value)
+
+
+def getattrs(
+    __o: object, __names: List[str], __default: Optional[Any] = None, /
+) -> List[Any]:
+    """Get named attributes from an object.
+
+    Args:
+        __o: Object from which to get attributes.
+        __names: Names of attributes to get from object.
+        __default (optional): Default value when attribute doesn't exist.
+            Default ``None``.
+
+    Returns:
+        Attributes.
+
+    """
+    results = [getattr(__o, __name, __default) for __name in __names]
+    return results
+
+
+def setattrs(__o: object, __names: List[str], __values: List[Any], /) -> None:
+    """Set named attributes on an object.
+
+    Args:
+        __o: Object on which to set attributes.
+        __names: Names of attributes to set on object.
+        __values: Values to set for keys on object.
+
+    Returns:
+        Updated object.
+
+    """
+    for __name, __value in zip(__names, __values):
+        setattr(__o, __name, __value)
+
+
+def iter_getattr(__iter: Iterable[object], __name: str, /) -> List[Any]:
+    """Get a named attribute from each object.
+
+    Args:
+        __iter: Iterable object containing objects.
+        __name: Attribute for which to retrieve value.
+
+    Raises:
+        TypeError: when argument is not an iterable object.
+        ValueError: when not all items are mappings.
+
+    """
+    if not isinstance(__iter, Iterable):  # type: ignore
+        raise TypeError("must be an iterable object")
+
+    if not allinstance(__iter, object):
+        raise ValueError("all items within iterator must be objects")
+
+    results = [getattr(item, __name) for item in __iter]
+    return results
+
+
+def iter_setattr(
+    __iter: Iterable[Any], __name: str, __value: Any, /
+) -> Iterable[Any]:
+    """Sets the named attribute to the specified value on each object.
+
+    Args:
+        __iter: Iterable object containing objects.
+        __name: Attribute to set to value.
+        value: Value to which to set attribute.
+
+    Raises:
+        TypeError: when argument is not an iterable object.
+        ValueError: when not all items are objects.
+
+    """
+    if not isinstance(__iter, Iterable):  # type: ignore
+        raise TypeError("must be an iterable object")
+
+    if not allinstance(__iter, object):
+        raise ValueError("all items within iterator must be objects")
+
+    for item in __iter:
+        setattr(item, __name, __value)
+
+    return __iter