pyochain 0.5.0__py3-none-any.whl

pyochain/_dict/_funcs.py

@@ -0,0 +1,62 @@
+from typing import Any
+
+
+def dict_repr(
+    v: object,
+    depth: int = 0,
+    max_depth: int = 3,
+    max_items: int = 6,
+    max_str: int = 80,
+    indent: int = 2,
+) -> str:
+    pad = " " * (depth * indent)
+    if depth > max_depth:
+        return "…"
+    match v:
+        case dict():
+            items: list[tuple[str, Any]] = list(v.items())  # type: ignore
+            shown: list[tuple[str, Any]] = items[:max_items]
+            if (
+                all(
+                    not isinstance(val, dict) and not isinstance(val, list)
+                    for _, val in shown
+                )
+                and len(shown) <= 2
+            ):
+                body = ", ".join(
+                    f"{k!r}: {dict_repr(val, depth + 1)}" for k, val in shown
+                )
+                if len(items) > max_items:
+                    body += ", …"
+                return "{" + body + "}"
+            lines: list[str] = []
+            for k, val in shown:
+                lines.append(
+                    f"{pad}{' ' * indent}{k!r}: {dict_repr(val, depth + 1, max_depth, max_items, max_str, indent)}"
+                )
+            if len(items) > max_items:
+                lines.append(f"{pad}{' ' * indent}…")
+            return "{\n" + ",\n".join(lines) + f"\n{pad}" + "}"
+
+        case list():
+            elems: list[Any] = v[:max_items]  # type: ignore
+            if (
+                all(isinstance(x, (int, float, str, bool, type(None))) for x in elems)
+                and len(elems) <= 4
+            ):
+                body = ", ".join(dict_repr(x, depth + 1) for x in elems)
+                if len(v) > max_items:  # type: ignore
+                    body += ", …"
+                return "[" + body + "]"
+            lines = [
+                f"{pad}{' ' * indent}{dict_repr(x, depth + 1, max_depth, max_items, max_str, indent)}"
+                for x in elems
+            ]
+            if len(v) > max_items:  # type: ignore
+                lines.append(f"{pad}{' ' * indent}…")
+            return "[\n" + ",\n".join(lines) + f"\n{pad}" + "]"
+
+        case str():
+            return repr(v if len(v) <= max_str else v[:max_str] + "…")
+        case _:
+            return repr(v)

pyochain/_dict/_groups.py

@@ -0,0 +1,176 @@
+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.apply(_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.apply(_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.apply(_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}
+        >>>
+        >>> # --- Exemple 2: Agrégation plus complexe ---
+        >>> 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.apply(_group_by_value_agg)

pyochain/_dict/_iter.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from typing import TYPE_CHECKING, Concatenate
+
+import cytoolz as cz
+
+from .._core import MappingWrapper
+
+if TYPE_CHECKING:
+    from .._iter import Iter
+    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.from_(v), *args, **kwargs)
+
+            return cz.dicttoolz.valmap(_, data)
+
+        return self.apply(_itr)
+
+    def iter_keys(self) -> Iter[K]:
+        """
+        Return a Iter of the dict's keys.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({1: 2}).iter_keys().into(list)
+        [1]
+
+        ```
+        """
+        from .._iter import Iter
+
+        return Iter.from_(self.unwrap().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
+
+        return Iter.from_(self.unwrap().values())
+
+    def iter_items(self) -> Iter[tuple[K, V]]:
+        """
+        Return a 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
+
+        return Iter.from_(self.unwrap().items())

pyochain/_dict/_joins.py

@@ -0,0 +1,137 @@
+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.apply(_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.apply(_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], other: 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.apply(_diff, other)
+
+    def merge(self, *others: Mapping[K, V]) -> Dict[K, V]:
+        """
+        Merge other dicts into this one and return a new Dict.
+
+        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}
+
+        ```
+        """
+        return self.apply(cz.dicttoolz.merge, *others)
+
+    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.apply(_merge_with)