pyochain 0.5.0__py3-none-any.whl

pyochain/_dict/_main.py

@@ -0,0 +1,307 @@
+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 .._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 ._nested import NestedDict
+from ._process import ProcessDict
+
+
+class Dict[K, V](
+    ProcessDict[K, V],
+    IterDict[K, V],
+    NestedDict[K, V],
+    JoinsDict[K, V],
+    FilterDict[K, V],
+    GroupsDict[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]:
+        """
+        Create a Dict from a mapping or SupportsKeysAndGetItem.
+
+        Args:
+            data: A mapping or object supporting keys and item access to convert into a Dict.
+
+        ```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'}
+
+        ```
+        """
+        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 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}
+
+        ```
+        """
+        return self.apply(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.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.
+
+        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
+
+        ```
+        """
+        return (
+            self.unwrap() == other.unwrap()
+            if isinstance(other, Dict)
+            else self.unwrap() == other
+        )

pyochain/_dict/_nested.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from functools import partial
+from typing import TYPE_CHECKING, Any, Concatenate
+
+import cytoolz as cz
+
+from .._core import MappingWrapper
+
+if TYPE_CHECKING:
+    from .._dict import Dict
+
+
+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
+        Dict({
+            'person1': {'NAME': 'Alice', 'CITY': 'New York'},
+            'person2': {'NAME': 'Bob', 'CITY': 'Los Angeles'}
+        })
+
+        ```
+        """
+        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.apply(_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: dict[Any, Any], parent_key: str = "", current_depth: int = 1
+        ) -> dict[str, Any]:
+            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
+                    )
+                else:
+                    items.append((new_key, v))  # type: ignore
+            return dict(items)
+
+        return self.apply(_flatten)
+
+    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'}
+
+        ```
+        """
+        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'.
+
+        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)
+
+    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.apply(_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)

pyochain/_dict/_process.py

@@ -0,0 +1,171 @@
+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
+
+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.apply(_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}}}
+
+        ```
+        """
+        return self.apply(cz.dicttoolz.update_in, keys, func, default=default)
+
+    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}
+
+        ```
+        """
+        return self.apply(cz.dicttoolz.assoc, key, value)
+
+    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}
+
+        ```
+        """
+        return self.apply(cz.dicttoolz.dissoc, *keys)
+
+    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.apply(_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.apply(_sort)

pyochain/_iter/__init__.py

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