pyochain 0.5.3__py3-none-any.whl

pyochain/_dict/_nested.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from functools import partial
+from typing import TYPE_CHECKING, Any, Concatenate, TypeIs
+
+import cytoolz as cz
+
+from .._core import MappingWrapper
+
+if TYPE_CHECKING:
+    from ._main import Dict
+
+
+def _drop_nones(
+    data: dict[Any, Any] | list[Any], remove_empty: bool = True
+) -> dict[Any, Any] | list[Any] | None:
+    match data:
+        case dict():
+            pruned_dict: dict[Any, Any] = {}
+            for k, v in data.items():
+                pruned_v = _drop_nones(v, remove_empty)
+
+                is_empty = remove_empty and (pruned_v is None or pruned_v in ({}, []))
+                if not is_empty:
+                    pruned_dict[k] = pruned_v
+            return pruned_dict if pruned_dict or not remove_empty else None
+
+        case list():
+            pruned_list = [_drop_nones(item, remove_empty) for item in data]
+            if remove_empty:
+                pruned_list = [
+                    item
+                    for item in pruned_list
+                    if not (item is None or item in ({}, []))
+                ]
+            return pruned_list if pruned_list or not remove_empty else None
+
+        case _:
+            if remove_empty and data is None:
+                return None
+            return data
+
+
+class NestedDict[K, V](MappingWrapper[K, V]):
+    def struct[**P, R, U: dict[Any, Any]](
+        self: NestedDict[K, U],
+        func: Callable[Concatenate[Dict[K, U], P], R],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Dict[K, R]:
+        """
+        Apply a function to each value after wrapping it in a Dict.
+
+        Args:
+            func: Function to apply to each value after wrapping it in a Dict.
+            *args: Positional arguments to pass to the function.
+            **kwargs: Keyword arguments to pass to the function.
+
+        Syntactic sugar for `map_values(lambda data: func(pc.Dict(data), *args, **kwargs))`
+        ```python
+        >>> import pyochain as pc
+        >>> data = {
+        ...     "person1": {"name": "Alice", "age": 30, "city": "New York"},
+        ...     "person2": {"name": "Bob", "age": 25, "city": "Los Angeles"},
+        ... }
+        >>> pc.Dict(data).struct(lambda d: d.map_keys(str.upper).drop("AGE").unwrap())
+        ... # doctest: +NORMALIZE_WHITESPACE
+        {'person1': {'CITY': 'New York', 'NAME': 'Alice'},
+        'person2': {'CITY': 'Los Angeles', 'NAME': 'Bob'}}
+
+        ```
+        """
+        from ._main import Dict
+
+        def _struct(data: Mapping[K, U]) -> dict[K, R]:
+            def _(v: dict[Any, Any]) -> R:
+                return func(Dict(v), *args, **kwargs)
+
+            return cz.dicttoolz.valmap(_, data)
+
+        return self._new(_struct)
+
+    def flatten(
+        self: NestedDict[str, Any], sep: str = ".", max_depth: int | None = None
+    ) -> Dict[str, Any]:
+        """
+        Flatten a nested dictionary, concatenating keys with the specified separator.
+
+        Args:
+            sep: Separator to use when concatenating keys
+            max_depth: Maximum depth to flatten. If None, flattens completely.
+        ```python
+        >>> import pyochain as pc
+        >>> data = {
+        ...     "config": {"params": {"retries": 3, "timeout": 30}, "mode": "fast"},
+        ...     "version": 1.0,
+        ... }
+        >>> pc.Dict(data).flatten().unwrap()
+        {'config.params.retries': 3, 'config.params.timeout': 30, 'config.mode': 'fast', 'version': 1.0}
+        >>> pc.Dict(data).flatten(sep="_").unwrap()
+        {'config_params_retries': 3, 'config_params_timeout': 30, 'config_mode': 'fast', 'version': 1.0}
+        >>> pc.Dict(data).flatten(max_depth=1).unwrap()
+        {'config.params': {'retries': 3, 'timeout': 30}, 'config.mode': 'fast', 'version': 1.0}
+
+        ```
+        """
+
+        def _flatten(
+            d: Mapping[Any, Any], parent_key: str = "", current_depth: int = 1
+        ) -> dict[str, Any]:
+            def _can_recurse(v: object) -> TypeIs[Mapping[Any, Any]]:
+                return isinstance(v, Mapping) and (
+                    max_depth is None or current_depth < max_depth + 1
+                )
+
+            items: list[tuple[str, Any]] = []
+            for k, v in d.items():
+                new_key = parent_key + sep + k if parent_key else k
+                if _can_recurse(v):
+                    items.extend(_flatten(v, new_key, current_depth + 1).items())
+                else:
+                    items.append((new_key, v))
+            return dict(items)
+
+        return self._new(_flatten)
+
+    def unpivot(
+        self: NestedDict[str, Mapping[str, Any]],
+    ) -> Dict[str, dict[str, Any]]:
+        """
+        Unpivot a nested dictionary by swapping rows and columns.
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> data = {
+        ...     "row1": {"col1": "A", "col2": "B"},
+        ...     "row2": {"col1": "C", "col2": "D"},
+        ... }
+        >>> pc.Dict(data).unpivot()
+        ... # doctest: +NORMALIZE_WHITESPACE
+        {'col1': {'row1': 'A', 'row2': 'C'}, 'col2': {'row1': 'B', 'row2': 'D'}}
+        """
+
+        def _unpivot(
+            data: Mapping[str, Mapping[str, Any]],
+        ) -> dict[str, dict[str, Any]]:
+            out: dict[str, dict[str, Any]] = {}
+            for rkey, inner in data.items():
+                for ckey, val in inner.items():
+                    out.setdefault(ckey, {})[rkey] = val
+            return out
+
+        return self._new(_unpivot)
+
+    def with_nested_key(self, *keys: K, value: V) -> Dict[K, V]:
+        """
+        Set a nested key path and return a new Dict with new, potentially nested, key value pair.
+
+        Args:
+            *keys: Sequence of keys representing the nested path.
+            value: Value to set at the specified nested path.
+        ```python
+        >>> import pyochain as pc
+        >>> purchase = {
+        ...     "name": "Alice",
+        ...     "order": {"items": ["Apple", "Orange"], "costs": [0.50, 1.25]},
+        ...     "credit card": "5555-1234-1234-1234",
+        ... }
+        >>> pc.Dict(purchase).with_nested_key(
+        ...     "order", "costs", value=[0.25, 1.00]
+        ... ).unwrap()
+        {'name': 'Alice', 'order': {'items': ['Apple', 'Orange'], 'costs': [0.25, 1.0]}, 'credit card': '5555-1234-1234-1234'}
+
+        ```
+        """
+
+        def _with_nested_key(data: dict[K, V]) -> dict[K, V]:
+            return cz.dicttoolz.assoc_in(data, keys, value=value)
+
+        return self._new(_with_nested_key)
+
+    def pluck[U: str | int](self: NestedDict[U, Any], *keys: str) -> Dict[U, Any]:
+        """
+        Extract values from nested dictionaries using a sequence of keys.
+
+        Args:
+            *keys: Sequence of keys to extract values from the nested dictionaries.
+        ```python
+        >>> import pyochain as pc
+        >>> data = {
+        ...     "person1": {"name": "Alice", "age": 30},
+        ...     "person2": {"name": "Bob", "age": 25},
+        ... }
+        >>> pc.Dict(data).pluck("name").unwrap()
+        {'person1': 'Alice', 'person2': 'Bob'}
+
+        ```
+        """
+
+        getter = partial(cz.dicttoolz.get_in, keys)
+
+        def _pluck(data: Mapping[U, Any]) -> dict[U, Any]:
+            return cz.dicttoolz.valmap(getter, data)
+
+        return self._new(_pluck)
+
+    def get_in(self, *keys: K, default: Any = None) -> Any:
+        """
+        Retrieve a value from a nested dictionary structure.
+
+        Args:
+            *keys: Sequence of keys representing the nested path to retrieve the value.
+            default: Default value to return if the keys do not exist.
+
+        ```python
+        >>> import pyochain as pc
+        >>> data = {"a": {"b": {"c": 1}}}
+        >>> pc.Dict(data).get_in("a", "b", "c")
+        1
+        >>> pc.Dict(data).get_in("a", "x", default="Not Found")
+        'Not Found'
+
+        ```
+        """
+
+        def _get_in(data: Mapping[K, V]) -> Any:
+            return cz.dicttoolz.get_in(keys, data, default)
+
+        return self.into(_get_in)
+
+    def drop_nones(self, remove_empty: bool = True) -> Dict[K, V]:
+        """
+        Recursively drop None values from the dictionary.
+
+        Options to also remove empty dicts and lists.
+
+        Args:
+            remove_empty: If True (default), removes `None`, `{}` and `[]`.
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> data = {
+        ...     "a": 1,
+        ...     "b": None,
+        ...     "c": {},
+        ...     "d": [],
+        ...     "e": {"f": None, "g": 2},
+        ...     "h": [1, None, {}],
+        ...     "i": 0,
+        ... }
+        >>> p_data = pc.Dict(data)
+        >>>
+        >>> p_data.drop_nones().unwrap()
+        {'a': 1, 'e': {'g': 2}, 'h': [1], 'i': 0}
+        >>>
+        >>> p_data.drop_nones().unwrap()
+        {'a': 1, 'e': {'g': 2}, 'h': [1], 'i': 0}
+        >>>
+        >>> p_data.drop_nones(remove_empty=False).unwrap()
+        {'a': 1, 'b': None, 'c': {}, 'd': [], 'e': {'f': None, 'g': 2}, 'h': [1, None, {}], 'i': 0}
+
+        ```
+        """
+
+        def _apply_drop_nones(data: dict[K, V]) -> dict[Any, Any]:
+            result = _drop_nones(data, remove_empty)
+            return result if isinstance(result, dict) else dict()
+
+        return self._new(_apply_drop_nones)

pyochain/_dict/_process.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any, Concatenate
+
+import cytoolz as cz
+
+from .._core import MappingWrapper, SupportsRichComparison
+
+if TYPE_CHECKING:
+    from ._main import Dict
+
+
+class ProcessDict[K, V](MappingWrapper[K, V]):
+    def for_each[**P](
+        self,
+        func: Callable[Concatenate[K, V, P], Any],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Dict[K, V]:
+        """
+        Apply a function to each key-value pair in the dict for side effects.
+
+        Args:
+            func: Function to apply to each key-value pair.
+            *args: Positional arguments to pass to the function.
+            **kwargs: Keyword arguments to pass to the function.
+
+        Returns the original Dict unchanged.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({"a": 1, "b": 2}).for_each(
+        ...     lambda k, v: print(f"Key: {k}, Value: {v}")
+        ... ).unwrap()
+        Key: a, Value: 1
+        Key: b, Value: 2
+        {'a': 1, 'b': 2}
+
+        ```
+        """
+
+        def _for_each(data: dict[K, V]) -> dict[K, V]:
+            for k, v in data.items():
+                func(k, v, *args, **kwargs)
+            return data
+
+        return self._new(_for_each)
+
+    def update_in(
+        self, *keys: K, func: Callable[[V], V], default: V | None = None
+    ) -> Dict[K, V]:
+        """
+        Update value in a (potentially) nested dictionary.
+
+        Args:
+            *keys: Sequence of keys representing the nested path to update.
+            func: Function to apply to the value at the specified path.
+            default: Default value to use if the path does not exist, by default None
+
+        Applies the func to the value at the path specified by keys, returning a new Dict with the updated value.
+
+        If the path does not exist, it will be created with the default value (if provided) before applying func.
+        ```python
+        >>> import pyochain as pc
+        >>> inc = lambda x: x + 1
+        >>> pc.Dict({"a": 0}).update_in("a", func=inc).unwrap()
+        {'a': 1}
+        >>> transaction = {
+        ...     "name": "Alice",
+        ...     "purchase": {"items": ["Apple", "Orange"], "costs": [0.50, 1.25]},
+        ...     "credit card": "5555-1234-1234-1234",
+        ... }
+        >>> pc.Dict(transaction).update_in("purchase", "costs", func=sum).unwrap()
+        {'name': 'Alice', 'purchase': {'items': ['Apple', 'Orange'], 'costs': 1.75}, 'credit card': '5555-1234-1234-1234'}
+        >>> # updating a value when k0 is not in d
+        >>> pc.Dict({}).update_in(1, 2, 3, func=str, default="bar").unwrap()
+        {1: {2: {3: 'bar'}}}
+        >>> pc.Dict({1: "foo"}).update_in(2, 3, 4, func=inc, default=0).unwrap()
+        {1: 'foo', 2: {3: {4: 1}}}
+
+        ```
+        """
+
+        def _update_in(data: dict[K, V]) -> dict[K, V]:
+            return cz.dicttoolz.update_in(data, keys, func, default=default)
+
+        return self._new(_update_in)
+
+    def with_key(self, key: K, value: V) -> Dict[K, V]:
+        """
+        Return a new Dict with key set to value.
+
+        Args:
+            key: Key to set in the dictionary.
+            value: Value to associate with the specified key.
+
+        Does not modify the initial dictionary.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({"x": 1}).with_key("x", 2).unwrap()
+        {'x': 2}
+        >>> pc.Dict({"x": 1}).with_key("y", 3).unwrap()
+        {'x': 1, 'y': 3}
+        >>> pc.Dict({}).with_key("x", 1).unwrap()
+        {'x': 1}
+
+        ```
+        """
+
+        def _with_key(data: dict[K, V]) -> dict[K, V]:
+            return cz.dicttoolz.assoc(data, key, value)
+
+        return self._new(_with_key)
+
+    def drop(self, *keys: K) -> Dict[K, V]:
+        """
+        Return a new Dict with given keys removed.
+
+        Args:
+            *keys: Sequence of keys to remove from the dictionary.
+
+        New dict has d[key] deleted for each supplied key.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({"x": 1, "y": 2}).drop("y").unwrap()
+        {'x': 1}
+        >>> pc.Dict({"x": 1, "y": 2}).drop("y", "x").unwrap()
+        {}
+        >>> pc.Dict({"x": 1}).drop("y").unwrap()  # Ignores missing keys
+        {'x': 1}
+        >>> pc.Dict({1: 2, 3: 4}).drop(1).unwrap()
+        {3: 4}
+
+        ```
+        """
+
+        def _drop(data: dict[K, V]) -> dict[K, V]:
+            return cz.dicttoolz.dissoc(data, *keys)
+
+        return self._new(_drop)
+
+    def rename(self, mapping: Mapping[K, K]) -> Dict[K, V]:
+        """
+        Return a new Dict with keys renamed according to the mapping.
+
+        Args:
+            mapping: A dictionary mapping old keys to new keys.
+
+        Keys not in the mapping are kept as is.
+        ```python
+        >>> import pyochain as pc
+        >>> d = {"a": 1, "b": 2, "c": 3}
+        >>> mapping = {"b": "beta", "c": "gamma"}
+        >>> pc.Dict(d).rename(mapping).unwrap()
+        {'a': 1, 'beta': 2, 'gamma': 3}
+
+        ```
+        """
+
+        def _rename(data: dict[K, V]) -> dict[K, V]:
+            return {mapping.get(k, k): v for k, v in data.items()}
+
+        return self._new(_rename)
+
+    def sort(self, reverse: bool = False) -> Dict[K, V]:
+        """
+        Sort the dictionary by its keys and return a new Dict.
+
+        Args:
+            reverse: Whether to sort in descending order. Defaults to False.
+
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({"b": 2, "a": 1}).sort().unwrap()
+        {'a': 1, 'b': 2}
+
+        ```
+        """
+
+        def _sort(data: dict[K, V]) -> dict[K, V]:
+            return dict(sorted(data.items(), reverse=reverse))
+
+        return self._new(_sort)
+
+    def sort_values[U: SupportsRichComparison[Any]](
+        self: ProcessDict[K, U], reverse: bool = False
+    ) -> Dict[K, U]:
+        """
+        Sort the dictionary by its values and return a new Dict.
+
+        Args:
+            reverse: Whether to sort in descending order. Defaults to False.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({"a": 2, "b": 1}).sort_values().unwrap()
+        {'b': 1, 'a': 2}
+
+        ```
+        """
+
+        def _sort_values(data: dict[K, U]) -> dict[K, U]:
+            return dict(sorted(data.items(), key=lambda item: item[1], reverse=reverse))
+
+        return self._new(_sort_values)

pyochain/_iter/__init__.py

@@ -0,0 +1,3 @@
+from ._main import Iter, Seq
+
+__all__ = ["Iter", "Seq"]