pyochain 0.5.1__py3-none-any.whl → 0.5.32__py3-none-any.whl

pyochain/_dict/_main.py

@@ -1,47 +1,51 @@
 from __future__ import annotations
 
-from collections import defaultdict
-from collections.abc import Callable, Mapping
-from functools import partial
-from typing import Any, Self
-
-import cytoolz as cz
+from collections.abc import Iterable, Mapping
+from typing import Any
 
 from .._core import SupportsKeysAndGetItem
-from ._exprs import IntoExpr, compute_exprs
 from ._filters import FilterDict
-from ._funcs import dict_repr
 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 Dict[K, V](
+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__ = ()
 
-    def __repr__(self) -> str:
-        return f"{self.__class__.__name__}({dict_repr(self.unwrap())})"
-
     @staticmethod
-    def from_[G, I](data: Mapping[G, I] | SupportsKeysAndGetItem[G, I]) -> Dict[G, I]:
+    def from_[G, I](
+        data: Mapping[G, I] | Iterable[tuple[G, I]] | SupportsKeysAndGetItem[G, I],
+    ) -> Dict[G, I]:
         """
-        Create a Dict from a mapping or SupportsKeysAndGetItem.
+        Create a Dict from a convertible value.
 
         Args:
-            data: A mapping or object supporting keys and item access to convert into a Dict.
+            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
@@ -57,6 +61,8 @@ class Dict[K, V](
         >>>
         >>> pc.Dict.from_(MyMapping()).unwrap()
         {1: 'a', 2: 'b', 3: 'c'}
+        >>> pc.Dict.from_([("d", "e"), ("f", "g")]).unwrap()
+        {'d': 'e', 'f': 'g'}
 
         ```
         """
@@ -84,224 +90,24 @@ class Dict[K, V](
         """
         return Dict(obj.__dict__)
 
-    def select(self: Dict[str, Any], *exprs: IntoExpr) -> Dict[str, Any]:
-        """
-        Select and alias fields from the dict based on expressions and/or strings.
-
-        Navigate nested fields using the `pyochain.key` function.
-
-        - Chain `key.key()` calls to access nested fields.
-        - Use `key.apply()` to transform values.
-        - Use `key.alias()` to rename fields in the resulting dict.
-
-        Args:
-            *exprs: Expressions or strings to select and alias fields from the dictionary.
-
-        ```python
-        >>> import pyochain as pc
-        >>> data = {
-        ...     "name": "Alice",
-        ...     "age": 30,
-        ...     "scores": {"eng": [85, 90, 95], "math": [80, 88, 92]},
-        ... }
-        >>> scores_expr = pc.key("scores")  # save an expression for reuse
-        >>> pc.Dict(data).select(
-        ...     pc.key("name").alias("student_name"),
-        ...     "age",  # shorthand for pc.key("age")
-        ...     scores_expr.key("math").alias("math_scores"),
-        ...     scores_expr.key("eng")
-        ...     .apply(lambda v: pc.Seq(v).mean())
-        ...     .alias("average_eng_score"),
-        ... ).unwrap()
-        {'student_name': 'Alice', 'age': 30, 'math_scores': [80, 88, 92], 'average_eng_score': 90}
-
-        ```
-        """
-
-        def _select(data: dict[str, Any]) -> dict[str, Any]:
-            return compute_exprs(exprs, data, {})
-
-        return self.apply(_select)
-
-    def with_fields(self: Dict[str, Any], *exprs: IntoExpr) -> Dict[str, Any]:
-        """
-        Merge aliased expressions into the root dict (overwrite on collision).
-
-        Args:
-            *exprs: Expressions to merge into the root dictionary.
-
-        ```python
-        >>> import pyochain as pc
-        >>> data = {
-        ...     "name": "Alice",
-        ...     "age": 30,
-        ...     "scores": {"eng": [85, 90, 95], "math": [80, 88, 92]},
-        ... }
-        >>> scores_expr = pc.key("scores")  # save an expression for reuse
-        >>> pc.Dict(data).with_fields(
-        ...     scores_expr.key("eng")
-        ...     .apply(lambda v: pc.Seq(v).mean())
-        ...     .alias("average_eng_score"),
-        ... ).unwrap()
-        {'name': 'Alice', 'age': 30, 'scores': {'eng': [85, 90, 95], 'math': [80, 88, 92]}, 'average_eng_score': 90}
-
-        ```
-        """
-
-        def _with_fields(data: dict[str, Any]) -> dict[str, Any]:
-            return compute_exprs(exprs, data, data.copy())
-
-        return self.apply(_with_fields)
-
-    def map_keys[T](self, func: Callable[[K], T]) -> Dict[T, V]:
-        """
-        Return a Dict with 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.apply(partial(cz.dicttoolz.keymap, func))
-
-    def map_values[T](self, func: Callable[[V], T]) -> Dict[K, T]:
-        """
-        Return a Dict with 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}
-
-        ```
+    def pivot(self, *indices: int) -> Dict[Any, Any]:
         """
-        return self.apply(partial(cz.dicttoolz.valmap, func))
+        Pivot a nested dictionary by rearranging the key levels according to order.
 
-    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.
+        Syntactic sugar for to_arrays().rearrange(*indices).to_records()
 
         Args:
-            func: Function to transform each (key, value) pair into a new (key, value) tuple.
+            indices: Indices specifying the new order of key levels
 
-        ```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.apply(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.apply(_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.apply(_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.apply(_implode)
-
-    def equals_to(self, other: Self | Mapping[Any, Any]) -> bool:
-        """
-        Check if two records are equal based on their data.
-
-        Args:
-            other: Another Dict or mapping to compare against.
+        Returns:
+            Pivoted dictionary with keys rearranged
 
         Example:
         ```python
         >>> import pyochain as pc
-        >>> d1 = pc.Dict({"a": 1, "b": 2})
-        >>> d2 = pc.Dict({"a": 1, "b": 2})
-        >>> d3 = pc.Dict({"a": 1, "b": 3})
-        >>> d1.equals_to(d2)
-        True
-        >>> d1.equals_to(d3)
-        False
-
-        ```
+        >>> 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.unwrap() == other.unwrap()
-            if isinstance(other, Dict)
-            else self.unwrap() == other
-        )
+
+        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)

pyochain/_dict/_nested.py

@@ -2,14 +2,44 @@ from __future__ import annotations
 
 from collections.abc import Callable, Mapping
 from functools import partial
-from typing import TYPE_CHECKING, Any, Concatenate
+from typing import TYPE_CHECKING, Any, Concatenate, TypeIs
 
 import cytoolz as cz
 
 from .._core import MappingWrapper
 
 if TYPE_CHECKING:
-    from .._dict import Dict
+    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]):
@@ -36,10 +66,8 @@ class NestedDict[K, V](MappingWrapper[K, V]):
         ... }
         >>> pc.Dict(data).struct(lambda d: d.map_keys(str.upper).drop("AGE").unwrap())
         ... # doctest: +NORMALIZE_WHITESPACE
-        Dict({
-            'person1': {'NAME': 'Alice', 'CITY': 'New York'},
-            'person2': {'NAME': 'Bob', 'CITY': 'Los Angeles'}
-        })
+        {'person1': {'CITY': 'New York', 'NAME': 'Alice'},
+        'person2': {'CITY': 'Los Angeles', 'NAME': 'Bob'}}
 
         ```
         """
@@ -51,7 +79,7 @@ class NestedDict[K, V](MappingWrapper[K, V]):
 
             return cz.dicttoolz.valmap(_, data)
 
-        return self.apply(_struct)
+        return self._new(_struct)
 
     def flatten(
         self: NestedDict[str, Any], sep: str = ".", max_depth: int | None = None
@@ -79,22 +107,52 @@ class NestedDict[K, V](MappingWrapper[K, V]):
         """
 
         def _flatten(
-            d: dict[Any, Any], parent_key: str = "", current_depth: int = 1
+            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 isinstance(v, dict) and (
-                    max_depth is None or current_depth < max_depth + 1
-                ):
-                    items.extend(
-                        _flatten(v, new_key, current_depth + 1).items()  # type: ignore
-                    )
+                if _can_recurse(v):
+                    items.extend(_flatten(v, new_key, current_depth + 1).items())
                 else:
-                    items.append((new_key, v))  # type: ignore
+                    items.append((new_key, v))
             return dict(items)
 
-        return self.apply(_flatten)
+        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]:
         """
@@ -117,56 +175,11 @@ class NestedDict[K, V](MappingWrapper[K, V]):
 
         ```
         """
-        return self.apply(cz.dicttoolz.assoc_in, keys, value=value)
-
-    def schema(self, max_depth: int = 1) -> Dict[str, Any]:
-        """
-        Return the schema of the dictionary up to a maximum depth.
 
-        Args:
-            max_depth: Maximum depth to inspect. Nested dicts beyond this depth are marked as 'dict'.
+        def _with_nested_key(data: dict[K, V]) -> dict[K, V]:
+            return cz.dicttoolz.assoc_in(data, keys, value=value)
 
-        When the max depth is reached, nested dicts are marked as 'dict'.
-        For lists, only the first element is inspected.
-        ```python
-        >>> import pyochain as pc
-        >>> # Depth 2: we see up to level2
-        >>> data = {
-        ...     "level1": {"level2": {"level3": {"key": "value"}}},
-        ...     "other_key": 123,
-        ...     "list_key": [{"sub_key": "sub_value"}],
-        ... }
-        >>> pc.Dict(data).schema(max_depth=1).unwrap()
-        {'level1': 'dict', 'other_key': 'int', 'list_key': 'list'}
-        >>> pc.Dict(data).schema(max_depth=2).unwrap()
-        {'level1': {'level2': 'dict'}, 'other_key': 'int', 'list_key': 'dict'}
-        >>>
-        >>> # Depth 3: we see up to level3
-        >>> pc.Dict(data).schema(max_depth=3).unwrap()
-        {'level1': {'level2': {'level3': 'dict'}}, 'other_key': 'int', 'list_key': {'sub_key': 'str'}}
-
-        ```
-        """
-
-        def _schema(data: dict[Any, Any]) -> Any:
-            def _recurse_schema(node: Any, current_depth: int) -> Any:
-                if isinstance(node, dict):
-                    if current_depth >= max_depth:
-                        return "dict"
-                    return {
-                        k: _recurse_schema(v, current_depth + 1)
-                        for k, v in node.items()  # type: ignore
-                    }
-                elif cz.itertoolz.isiterable(node):
-                    if current_depth >= max_depth:
-                        return type(node).__name__
-                    return _recurse_schema(cz.itertoolz.first(node), current_depth + 1)
-                else:
-                    return type(node).__name__
-
-            return _recurse_schema(data, 0)
-
-        return self.apply(_schema)
+        return self._new(_with_nested_key)
 
     def pluck[U: str | int](self: NestedDict[U, Any], *keys: str) -> Dict[U, Any]:
         """
@@ -191,7 +204,7 @@ class NestedDict[K, V](MappingWrapper[K, V]):
         def _pluck(data: Mapping[U, Any]) -> dict[U, Any]:
             return cz.dicttoolz.valmap(getter, data)
 
-        return self.apply(_pluck)
+        return self._new(_pluck)
 
     def get_in(self, *keys: K, default: Any = None) -> Any:
         """
@@ -216,3 +229,44 @@ class NestedDict[K, V](MappingWrapper[K, V]):
             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)