pyochain 0.5.3__py3-none-any.whl

pyochain/_dict/_groups.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+import cytoolz as cz
+
+from .._core import MappingWrapper
+
+if TYPE_CHECKING:
+    from ._main import Dict
+
+
+class GroupsDict[K, V](MappingWrapper[K, V]):
+    def group_by_value[G](self, func: Callable[[V], G]) -> Dict[G, dict[K, V]]:
+        """
+        Group dict items into sub-dictionaries based on a function of the value.
+
+        Args:
+            func: Function to determine the group for each value.
+
+        ```python
+        >>> import pyochain as pc
+        >>> d = {"a": 1, "b": 2, "c": 3, "d": 2}
+        >>> pc.Dict(d).group_by_value(lambda v: v % 2).unwrap()
+        {1: {'a': 1, 'c': 3}, 0: {'b': 2, 'd': 2}}
+
+        ```
+        """
+
+        def _group_by_value(data: dict[K, V]) -> dict[G, dict[K, V]]:
+            def _(kv: tuple[K, V]) -> G:
+                return func(kv[1])
+
+            return cz.dicttoolz.valmap(dict, cz.itertoolz.groupby(_, data.items()))
+
+        return self._new(_group_by_value)
+
+    def group_by_key[G](self, func: Callable[[K], G]) -> Dict[G, dict[K, V]]:
+        """
+        Group dict items into sub-dictionaries based on a function of the key.
+
+        Args:
+            func: Function to determine the group for each key.
+
+        ```python
+        >>> import pyochain as pc
+        >>> d = {"user_1": 10, "user_2": 20, "admin_1": 100}
+        >>> pc.Dict(d).group_by_key(lambda k: k.split("_")[0]).unwrap()
+        {'user': {'user_1': 10, 'user_2': 20}, 'admin': {'admin_1': 100}}
+
+        ```
+        """
+
+        def _group_by_key(data: dict[K, V]) -> dict[G, dict[K, V]]:
+            def _(kv: tuple[K, V]) -> G:
+                return func(kv[0])
+
+            return cz.dicttoolz.valmap(dict, cz.itertoolz.groupby(_, data.items()))
+
+        return self._new(_group_by_key)
+
+    def group_by_key_agg[G, R](
+        self,
+        key_func: Callable[[K], G],
+        agg_func: Callable[[Dict[K, V]], R],
+    ) -> Dict[G, R]:
+        """
+        Group by key function, then apply aggregation function to each sub-dict.
+
+        Args:
+            key_func: Function to determine the group for each key.
+            agg_func: Function to aggregate each sub-dictionary.
+
+        This avoids materializing intermediate `dict` objects if you only need
+        an aggregated result for each group.
+        ```python
+        >>> import pyochain as pc
+        >>>
+        >>> data = {"user_1": 10, "user_2": 20, "admin_1": 100}
+        >>> pc.Dict(data).group_by_key_agg(
+        ...     key_func=lambda k: k.split("_")[0],
+        ...     agg_func=lambda d: d.iter_values().sum(),
+        ... ).unwrap()
+        {'user': 30, 'admin': 100}
+        >>>
+        >>> data_files = {
+        ...     "file_a.txt": 100,
+        ...     "file_b.log": 20,
+        ...     "file_c.txt": 50,
+        ...     "file_d.log": 5,
+        ... }
+        >>>
+        >>> def get_stats(sub_dict: pc.Dict[str, int]) -> dict[str, Any]:
+        ...     return {
+        ...         "count": sub_dict.iter_keys().count(),
+        ...         "total_size": sub_dict.iter_values().sum(),
+        ...         "max_size": sub_dict.iter_values().max(),
+        ...         "files": sub_dict.iter_keys().sort().into(list),
+        ...     }
+        >>>
+        >>> pc.Dict(data_files).group_by_key_agg(
+        ...     key_func=lambda k: k.split(".")[-1], agg_func=get_stats
+        ... ).sort().unwrap()
+        {'log': {'count': 2, 'total_size': 25, 'max_size': 20, 'files': ['file_b.log', 'file_d.log']}, 'txt': {'count': 2, 'total_size': 150, 'max_size': 100, 'files': ['file_a.txt', 'file_c.txt']}}
+
+        ```
+        """
+        from ._main import Dict
+
+        def _group_by_key_agg(data: dict[K, V]) -> dict[G, R]:
+            def _key_func(kv: tuple[K, V]) -> G:
+                return key_func(kv[0])
+
+            def _agg_func(items: list[tuple[K, V]]) -> R:
+                return agg_func(Dict(dict(items)))
+
+            groups = cz.itertoolz.groupby(_key_func, data.items())
+            return cz.dicttoolz.valmap(_agg_func, groups)
+
+        return self._new(_group_by_key_agg)
+
+    def group_by_value_agg[G, R](
+        self,
+        value_func: Callable[[V], G],
+        agg_func: Callable[[Dict[K, V]], R],
+    ) -> Dict[G, R]:
+        """
+        Group by value function, then apply aggregation function to each sub-dict.
+
+        Args:
+            value_func: Function to determine the group for each value.
+            agg_func: Function to aggregate each sub-dictionary.
+
+        This avoids materializing intermediate `dict` objects if you only need
+        an aggregated result for each group.
+        ```python
+        >>> import pyochain as pc
+        >>>
+        >>> data = {"math": "A", "physics": "B", "english": "A"}
+        >>> pc.Dict(data).group_by_value_agg(
+        ...     value_func=lambda grade: grade,
+        ...     agg_func=lambda d: d.iter_keys().count(),
+        ... ).unwrap()
+        {'A': 2, 'B': 1}
+        >>> # Second example
+        >>> sales_data = {
+        ...     "store_1": "Electronics",
+        ...     "store_2": "Groceries",
+        ...     "store_3": "Electronics",
+        ...     "store_4": "Clothing",
+        ... }
+        >>>
+        >>> # Obtain the first store for each category (after sorting store names)
+        >>> pc.Dict(sales_data).group_by_value_agg(
+        ...     value_func=lambda category: category,
+        ...     agg_func=lambda d: d.iter_keys().sort().first(),
+        ... ).sort().unwrap()
+        {'Clothing': 'store_4', 'Electronics': 'store_1', 'Groceries': 'store_2'}
+
+        ```
+        """
+        from ._main import Dict
+
+        def _group_by_value_agg(data: dict[K, V]) -> dict[G, R]:
+            def _key_func(kv: tuple[K, V]) -> G:
+                return value_func(kv[1])
+
+            def _agg_func(items: list[tuple[K, V]]) -> R:
+                return agg_func(Dict(dict(items)))
+
+            groups = cz.itertoolz.groupby(_key_func, data.items())
+            return cz.dicttoolz.valmap(_agg_func, groups)
+
+        return self._new(_group_by_value_agg)

pyochain/_dict/_iter.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from typing import TYPE_CHECKING, Any, Concatenate
+
+import cytoolz as cz
+
+from .._core import MappingWrapper
+
+if TYPE_CHECKING:
+    from .._iter import Iter, Seq
+    from ._main import Dict
+
+
+class IterDict[K, V](MappingWrapper[K, V]):
+    def itr[**P, R, U](
+        self: MappingWrapper[K, Iterable[U]],
+        func: Callable[Concatenate[Iter[U], P], R],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Dict[K, R]:
+        """
+        Apply a function to each value after wrapping it in an Iter.
+
+        Args:
+            func: Function to apply to each value after wrapping it in an Iter.
+            *args: Positional arguments to pass to the function.
+            **kwargs: Keyword arguments to pass to the function.
+
+        Syntactic sugar for `map_values(lambda data: func(Iter(data), *args, **kwargs))`
+        ```python
+        >>> import pyochain as pc
+        >>> data = {
+        ...     "numbers1": [1, 2, 3],
+        ...     "numbers2": [4, 5, 6],
+        ... }
+        >>> pc.Dict(data).itr(lambda v: v.repeat(5).flatten().sum()).unwrap()
+        {'numbers1': 30, 'numbers2': 75}
+
+        ```
+        """
+        from .._iter import Iter
+
+        def _itr(data: Mapping[K, Iterable[U]]) -> dict[K, R]:
+            def _(v: Iterable[U]) -> R:
+                return func(Iter(iter(v)), *args, **kwargs)
+
+            return cz.dicttoolz.valmap(_, data)
+
+        return self._new(_itr)
+
+    def iter_keys(self) -> Iter[K]:
+        """
+        Return an Iter of the dict's keys.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({1: 2}).iter_keys().into(list)
+        [1]
+
+        ```
+        """
+        from .._iter import Iter
+
+        def _keys(data: dict[K, V]) -> Iter[K]:
+            return Iter(iter(data.keys()))
+
+        return self.into(_keys)
+
+    def iter_values(self) -> Iter[V]:
+        """
+        Return an Iter of the dict's values.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({1: 2}).iter_values().into(list)
+        [2]
+
+        ```
+        """
+        from .._iter import Iter
+
+        def _values(data: dict[K, V]) -> Iter[V]:
+            return Iter(iter(data.values()))
+
+        return self.into(_values)
+
+    def iter_items(self) -> Iter[tuple[K, V]]:
+        """
+        Return an Iter of the dict's items.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({1: 2}).iter_items().into(list)
+        [(1, 2)]
+
+        ```
+        """
+        from .._iter import Iter
+
+        def _items(data: dict[K, V]) -> Iter[tuple[K, V]]:
+            return Iter(iter(data.items()))
+
+        return self.into(_items)
+
+    def to_arrays(self) -> Seq[list[Any]]:
+        """
+        Convert the nested dictionary into a sequence of arrays.
+
+        The sequence represents all paths from root to leaves.
+
+        ```python
+        >>> import pyochain as pc
+        >>> data = {
+        ...     "a": {"b": 1, "c": 2},
+        ...     "d": {"e": {"f": 3}},
+        ... }
+        >>> pc.Dict(data).to_arrays().unwrap()
+        [['a', 'b', 1], ['a', 'c', 2], ['d', 'e', 'f', 3]]
+
+        ```
+        """
+        from .._iter import Seq
+
+        def _to_arrays(d: Mapping[Any, Any]) -> list[list[Any]]:
+            """from dictutils.pivot"""
+            match d:
+                case Mapping():
+                    arr: list[Any] = []
+                    for k, v in d.items():
+                        for el in _to_arrays(v):
+                            arr.append([k] + el)
+                    return arr
+
+                case _:
+                    return [[d]]
+
+        return Seq(self.into(_to_arrays))

pyochain/_dict/_joins.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from typing import TYPE_CHECKING
+
+import cytoolz as cz
+
+from .._core import MappingWrapper
+
+if TYPE_CHECKING:
+    from ._main import Dict
+
+
+class JoinsDict[K, V](MappingWrapper[K, V]):
+    def inner_join[W](self, other: Mapping[K, W]) -> Dict[K, tuple[V, W]]:
+        """
+        Performs an inner join with another mapping based on keys.
+
+        Args:
+            other: The mapping to join with.
+
+        Only keys present in both mappings are kept.
+        ```python
+        >>> import pyochain as pc
+        >>> d1 = {"a": 1, "b": 2}
+        >>> d2 = {"b": 10, "c": 20}
+        >>> pc.Dict(d1).inner_join(d2).unwrap()
+        {'b': (2, 10)}
+
+        ```
+        """
+
+        def _inner_join(data: Mapping[K, V]) -> dict[K, tuple[V, W]]:
+            return {k: (v, other[k]) for k, v in data.items() if k in other}
+
+        return self._new(_inner_join)
+
+    def left_join[W](self, other: Mapping[K, W]) -> Dict[K, tuple[V, W | None]]:
+        """
+        Performs a left join with another mapping based on keys.
+
+        Args:
+            other: The mapping to join with.
+
+        All keys from the left dictionary (self) are kept.
+        ```python
+        >>> import pyochain as pc
+        >>> d1 = {"a": 1, "b": 2}
+        >>> d2 = {"b": 10, "c": 20}
+        >>> pc.Dict(d1).left_join(d2).unwrap()
+        {'a': (1, None), 'b': (2, 10)}
+
+        ```
+        """
+
+        def _left_join(data: Mapping[K, V]) -> dict[K, tuple[V, W | None]]:
+            return {k: (v, other.get(k)) for k, v in data.items()}
+
+        return self._new(_left_join)
+
+    def diff(self, other: Mapping[K, V]) -> Dict[K, tuple[V | None, V | None]]:
+        """
+        Returns a dict of the differences between this dict and another.
+
+        Args:
+            other: The mapping to compare against.
+
+        The keys of the returned dict are the keys that are not shared or have different values.
+        The values are tuples containing the value from self and the value from other.
+        ```python
+        >>> import pyochain as pc
+        >>> d1 = {"a": 1, "b": 2, "c": 3}
+        >>> d2 = {"b": 2, "c": 4, "d": 5}
+        >>> pc.Dict(d1).diff(d2).sort().unwrap()
+        {'a': (1, None), 'c': (3, 4), 'd': (None, 5)}
+
+        ```
+        """
+
+        def _diff(data: Mapping[K, V]) -> dict[K, tuple[V | None, V | None]]:
+            all_keys: set[K] = data.keys() | other.keys()
+            diffs: dict[K, tuple[V | None, V | None]] = {}
+            for key in all_keys:
+                self_val = data.get(key)
+                other_val = other.get(key)
+                if self_val != other_val:
+                    diffs[key] = (self_val, other_val)
+            return diffs
+
+        return self._new(_diff)
+
+    def merge(self, *others: Mapping[K, V]) -> Dict[K, V]:
+        """
+        Merge other dicts into this one.
+
+        Args:
+            *others: One or more mappings to merge into the current dictionary.
+
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({1: "one"}).merge({2: "two"}).unwrap()
+        {1: 'one', 2: 'two'}
+        >>> # Later dictionaries have precedence
+        >>> pc.Dict({1: 2, 3: 4}).merge({3: 3, 4: 4}).unwrap()
+        {1: 2, 3: 3, 4: 4}
+
+        ```
+        """
+
+        def _merge(data: Mapping[K, V]) -> dict[K, V]:
+            return cz.dicttoolz.merge(data, *others)
+
+        return self._new(_merge)
+
+    def merge_with(
+        self, *others: Mapping[K, V], func: Callable[[Iterable[V]], V]
+    ) -> Dict[K, V]:
+        """
+        Merge dicts using a function to combine values for duplicate keys.
+
+        Args:
+            *others: One or more mappings to merge into the current dictionary.
+            func: Function to combine values for duplicate keys.
+
+        A key may occur in more than one dict, and all values mapped from the key will be passed to the function as a list, such as func([val1, val2, ...]).
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({1: 1, 2: 2}).merge_with({1: 10, 2: 20}, func=sum).unwrap()
+        {1: 11, 2: 22}
+        >>> pc.Dict({1: 1, 2: 2}).merge_with({2: 20, 3: 30}, func=max).unwrap()
+        {1: 1, 2: 20, 3: 30}
+
+        ```
+        """
+
+        def _merge_with(data: Mapping[K, V]) -> dict[K, V]:
+            return cz.dicttoolz.merge_with(func, data, *others)
+
+        return self._new(_merge_with)

pyochain/_dict/_main.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from .._core import SupportsKeysAndGetItem
+from ._filters import FilterDict
+from ._groups import GroupsDict
+from ._iter import IterDict
+from ._joins import JoinsDict
+from ._maps import MapDict
+from ._nested import NestedDict
+from ._process import ProcessDict
+
+
+class DictCommonMethods[K, V](
+    ProcessDict[K, V],
+    IterDict[K, V],
+    NestedDict[K, V],
+    MapDict[K, V],
+    JoinsDict[K, V],
+    FilterDict[K, V],
+    GroupsDict[K, V],
+):
+    pass
+
+
+class Dict[K, V](DictCommonMethods[K, V]):
+    """
+    Wrapper for Python dictionaries with chainable methods.
+    """
+
+    __slots__ = ()
+
+    @staticmethod
+    def from_[G, I](
+        data: Mapping[G, I] | Iterable[tuple[G, I]] | SupportsKeysAndGetItem[G, I],
+    ) -> Dict[G, I]:
+        """
+        Create a Dict from a convertible value.
+
+        Args:
+            data: A mapping, Iterable of tuples, or object supporting keys and item access to convert into a Dict.
+
+        Returns:
+            A Dict instance containing the data from the input.
+
+        Example:
+
+        ```python
+        >>> import pyochain as pc
+        >>> class MyMapping:
+        ...     def __init__(self):
+        ...         self._data = {1: "a", 2: "b", 3: "c"}
+        ...
+        ...     def keys(self):
+        ...         return self._data.keys()
+        ...
+        ...     def __getitem__(self, key):
+        ...         return self._data[key]
+        >>>
+        >>> pc.Dict.from_(MyMapping()).unwrap()
+        {1: 'a', 2: 'b', 3: 'c'}
+        >>> pc.Dict.from_([("d", "e"), ("f", "g")]).unwrap()
+        {'d': 'e', 'f': 'g'}
+
+        ```
+        """
+        return Dict(dict(data))
+
+    @staticmethod
+    def from_object(obj: object) -> Dict[str, Any]:
+        """
+        Create a Dict from an object's __dict__ attribute.
+
+        Args:
+            obj: The object whose `__dict__` attribute will be used to create the Dict.
+
+        ```python
+        >>> import pyochain as pc
+        >>> class Person:
+        ...     def __init__(self, name: str, age: int):
+        ...         self.name = name
+        ...         self.age = age
+        >>> person = Person("Alice", 30)
+        >>> pc.Dict.from_object(person).unwrap()
+        {'name': 'Alice', 'age': 30}
+
+        ```
+        """
+        return Dict(obj.__dict__)
+
+    def pivot(self, *indices: int) -> Dict[Any, Any]:
+        """
+        Pivot a nested dictionary by rearranging the key levels according to order.
+
+        Syntactic sugar for to_arrays().rearrange(*indices).to_records()
+
+        Args:
+            indices: Indices specifying the new order of key levels
+
+        Returns:
+            Pivoted dictionary with keys rearranged
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> d = {"A": {"X": 1, "Y": 2}, "B": {"X": 3, "Y": 4}}
+        >>> pc.Dict(d).pivot(1, 0).unwrap()
+        {'X': {'A': 1, 'B': 3}, 'Y': {'A': 2, 'B': 4}}
+        """
+
+        return self.to_arrays().rearrange(*indices).to_records()

pyochain/_dict/_maps.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Callable
+from functools import partial
+from typing import TYPE_CHECKING
+
+import cytoolz as cz
+
+from .._core import MappingWrapper
+
+if TYPE_CHECKING:
+    from ._main import Dict
+
+
+class MapDict[K, V](MappingWrapper[K, V]):
+    def map_keys[T](self, func: Callable[[K], T]) -> Dict[T, V]:
+        """
+        Return keys transformed by func.
+
+        Args:
+            func: Function to apply to each key in the dictionary.
+
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({"Alice": [20, 15, 30], "Bob": [10, 35]}).map_keys(
+        ...     str.lower
+        ... ).unwrap()
+        {'alice': [20, 15, 30], 'bob': [10, 35]}
+        >>>
+        >>> pc.Dict({1: "a"}).map_keys(str).unwrap()
+        {'1': 'a'}
+
+        ```
+        """
+        return self._new(partial(cz.dicttoolz.keymap, func))
+
+    def map_values[T](self, func: Callable[[V], T]) -> Dict[K, T]:
+        """
+        Return values transformed by func.
+
+        Args:
+            func: Function to apply to each value in the dictionary.
+
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({"Alice": [20, 15, 30], "Bob": [10, 35]}).map_values(sum).unwrap()
+        {'Alice': 65, 'Bob': 45}
+        >>>
+        >>> pc.Dict({1: 1}).map_values(lambda v: v + 1).unwrap()
+        {1: 2}
+
+        ```
+        """
+        return self._new(partial(cz.dicttoolz.valmap, func))
+
+    def map_items[KR, VR](
+        self,
+        func: Callable[[tuple[K, V]], tuple[KR, VR]],
+    ) -> Dict[KR, VR]:
+        """
+        Transform (key, value) pairs using a function that takes a (key, value) tuple.
+
+        Args:
+            func: Function to transform each (key, value) pair into a new (key, value) tuple.
+
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({"Alice": 10, "Bob": 20}).map_items(
+        ...     lambda kv: (kv[0].upper(), kv[1] * 2)
+        ... ).unwrap()
+        {'ALICE': 20, 'BOB': 40}
+
+        ```
+        """
+        return self._new(partial(cz.dicttoolz.itemmap, func))
+
+    def map_kv[KR, VR](
+        self,
+        func: Callable[[K, V], tuple[KR, VR]],
+    ) -> Dict[KR, VR]:
+        """
+        Transform (key, value) pairs using a function that takes key and value as separate arguments.
+
+        Args:
+            func: Function to transform each key and value into a new (key, value) tuple.
+
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({1: 2}).map_kv(lambda k, v: (k + 1, v * 10)).unwrap()
+        {2: 20}
+
+        ```
+        """
+
+        def _map_kv(data: dict[K, V]) -> dict[KR, VR]:
+            def _(kv: tuple[K, V]) -> tuple[KR, VR]:
+                return func(kv[0], kv[1])
+
+            return cz.dicttoolz.itemmap(_, data)
+
+        return self._new(_map_kv)
+
+    def invert(self) -> Dict[V, list[K]]:
+        """
+        Invert the dictionary, grouping keys by common (and hashable) values.
+        ```python
+        >>> import pyochain as pc
+        >>> d = {"a": 1, "b": 2, "c": 1}
+        >>> pc.Dict(d).invert().unwrap()
+        {1: ['a', 'c'], 2: ['b']}
+
+        ```
+        """
+
+        def _invert(data: dict[K, V]) -> dict[V, list[K]]:
+            inverted: dict[V, list[K]] = defaultdict(list)
+            for k, v in data.items():
+                inverted[v].append(k)
+            return dict(inverted)
+
+        return self._new(_invert)
+
+    def implode(self) -> Dict[K, list[V]]:
+        """
+        Nest all the values in lists.
+        syntactic sugar for map_values(lambda v: [v])
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({1: 2, 3: 4}).implode().unwrap()
+        {1: [2], 3: [4]}
+
+        ```
+        """
+
+        def _implode(data: dict[K, V]) -> dict[K, list[V]]:
+            def _(v: V) -> list[V]:
+                return [v]
+
+            return cz.dicttoolz.valmap(_, data)
+
+        return self._new(_implode)