pyochain 0.5.0__py3-none-any.whl

pyochain/__init__.py

@@ -0,0 +1,5 @@
+from ._core import Wrapper
+from ._dict import Dict, Expr, key
+from ._iter import Iter, Seq
+
+__all__ = ["Dict", "Iter", "Wrapper", "key", "Seq", "Expr"]

pyochain/_core/__init__.py

@@ -0,0 +1,21 @@
+from ._main import CommonBase, IterWrapper, MappingWrapper, Pipeable, Wrapper
+from ._protocols import (
+    Peeked,
+    SizedIterable,
+    SupportsAllComparisons,
+    SupportsKeysAndGetItem,
+    SupportsRichComparison,
+)
+
+__all__ = [
+    "MappingWrapper",
+    "CommonBase",
+    "IterWrapper",
+    "Wrapper",
+    "SupportsAllComparisons",
+    "SupportsRichComparison",
+    "SupportsKeysAndGetItem",
+    "Peeked",
+    "SizedIterable",
+    "Pipeable",
+]

pyochain/_core/_main.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Collection, Iterable, Iterator
+from typing import TYPE_CHECKING, Any, Concatenate, Self
+
+if TYPE_CHECKING:
+    from .._dict import Dict
+    from .._iter import Iter, Seq
+
+
+class Pipeable:
+    def pipe[**P, R](
+        self,
+        func: Callable[Concatenate[Self, P], R],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> R:
+        """Pipe the instance in the function and return the result."""
+        return func(self, *args, **kwargs)
+
+
+class CommonBase[T](ABC, Pipeable):
+    """
+    Base class for all wrappers.
+    You can subclass this to create your own wrapper types.
+    The pipe unwrap method must be implemented to allow piping functions that transform the underlying data type, whilst retaining the wrapper.
+    """
+
+    _data: T
+
+    __slots__ = ("_data",)
+
+    def __init__(self, data: T) -> None:
+        self._data = data
+
+    @abstractmethod
+    def apply[**P](
+        self,
+        func: Callable[Concatenate[T, P], Any],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Any:
+        raise NotImplementedError
+
+    def println(self, pretty: bool = True) -> Self:
+        """
+        Print the underlying data and return self for chaining.
+
+        Useful for debugging, simply insert `.println()` in the chain,
+        and then removing it will not affect the rest of the chain.
+        """
+        from pprint import pprint
+
+        if pretty:
+            pprint(self.unwrap(), sort_dicts=False)
+        else:
+            print(self.unwrap())
+        return self
+
+    def unwrap(self) -> T:
+        """
+        Return the underlying data.
+
+        This is a terminal operation.
+        """
+        return self._data
+
+    def into[**P, R](
+        self,
+        func: Callable[Concatenate[T, P], R],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> R:
+        """
+        Pass the *unwrapped* underlying data into a function.
+
+        The result is not wrapped.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_(range(5)).into(list)
+        [0, 1, 2, 3, 4]
+
+        ```
+        This is a core functionality that allows ending the chain whilst keeping the code style consistent.
+        """
+        return func(self.unwrap(), *args, **kwargs)
+
+
+class IterWrapper[T](CommonBase[Iterable[T]]):
+    _data: Iterable[T]
+
+    def apply[**P, R](
+        self,
+        func: Callable[Concatenate[Iterable[T], P], Iterator[R]],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Iter[R]:
+        """
+        Apply a function to the underlying iterable and return an Iter of the result.
+        Allow to pass user defined functions that transform the iterable while retaining the Iter wrapper.
+        Args:
+            func: Function to apply to the underlying iterable.
+            *args: Positional arguments to pass to the function.
+            **kwargs: Keyword arguments to pass to the function.
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> def double(data: Iterable[int]) -> Iterator[int]:
+        ...     return (x * 2 for x in data)
+        >>> pc.Iter.from_([1, 2, 3]).apply(double).into(list)
+        [2, 4, 6]
+        """
+        from .._iter import Iter
+
+        return Iter(self.into(func, *args, **kwargs))
+
+    def collect(self, factory: Callable[[Iterable[T]], Collection[T]] = list) -> Seq[T]:
+        """
+        Collect the elements into a sequence.
+        Args:
+            factory: A callable that takes an iterable and returns a collection. Defaults to list.
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_(range(5)).collect().unwrap()
+        [0, 1, 2, 3, 4]
+
+        ```
+        """
+        from .._iter import Seq
+
+        return Seq(self.into(factory))
+
+
+class MappingWrapper[K, V](CommonBase[dict[K, V]]):
+    _data: dict[K, V]
+
+    def apply[**P, KU, VU](
+        self,
+        func: Callable[Concatenate[dict[K, V], P], dict[KU, VU]],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Dict[KU, VU]:
+        """
+        Apply a function to the underlying dict and return a Dict of the result.
+        Allow to pass user defined functions that transform the dict while retaining the Dict wrapper.
+        Args:
+            func: Function to apply to the underlying dict.
+            *args: Positional arguments to pass to the function.
+            **kwargs: Keyword arguments to pass to the function.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> def invert_dict(d: dict[K, V]) -> dict[V, K]:
+        ...     return {v: k for k, v in d.items()}
+        >>> pc.Dict({'a': 1, 'b': 2}).apply(invert_dict).unwrap()
+        {1: 'a', 2: 'b'}
+
+        ```
+        """
+        from .._dict import Dict
+
+        return Dict(self.into(func, *args, **kwargs))
+
+
+class Wrapper[T](CommonBase[T]):
+    """
+    A generic Wrapper for any type.
+    The pipe into method is implemented to return a Wrapper of the result type.
+
+    This class is intended for use with other types/implementations that do not support the fluent/functional style.
+    This allow the use of a consistent code style across the code base.
+    """
+
+    def apply[**P, R](
+        self,
+        func: Callable[Concatenate[T, P], R],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Wrapper[R]:
+        return Wrapper(self.into(func, *args, **kwargs))

pyochain/_core/_protocols.py

@@ -0,0 +1,43 @@
+from collections.abc import Iterable, Iterator, Sized
+from typing import NamedTuple, Protocol
+
+
+class Peeked[T](NamedTuple):
+    value: T | tuple[T, ...]
+    sequence: Iterator[T]
+
+
+class SupportsDunderLT[T](Protocol):
+    def __lt__(self, other: T, /) -> bool: ...
+
+
+class SupportsDunderGT[T](Protocol):
+    def __gt__(self, other: T, /) -> bool: ...
+
+
+class SupportsDunderLE[T](Protocol):
+    def __le__(self, other: T, /) -> bool: ...
+
+
+class SupportsDunderGE[T](Protocol):
+    def __ge__(self, other: T, /) -> bool: ...
+
+
+class SupportsKeysAndGetItem[K, V](Protocol):
+    def keys(self) -> Iterable[K]: ...
+    def __getitem__(self, key: K, /) -> V: ...
+
+
+class SupportsAllComparisons[T](
+    SupportsDunderLT[T],
+    SupportsDunderGT[T],
+    SupportsDunderLE[T],
+    SupportsDunderGE[T],
+    Protocol,
+): ...
+
+
+type SupportsRichComparison[T] = SupportsDunderLT[T] | SupportsDunderGT[T]
+
+
+class SizedIterable[T](Sized, Iterable[T]): ...

pyochain/_dict/__init__.py

@@ -0,0 +1,4 @@
+from ._exprs import Expr, key
+from ._main import Dict
+
+__all__ = ["Dict", "key", "Expr"]

pyochain/_dict/_exprs.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import Any, Self, TypeGuard
+
+import cytoolz as cz
+
+from .._core import Pipeable
+
+
+@dataclass(slots=True)
+class Expr(Pipeable):
+    """
+    Represents an expression in the pipeline.
+
+    An Expr encapsulates a sequence of operations to be applied to keys on a python dict.
+
+    Each Expr instance maintains:
+    - A list of tokens representing the keys to access in the dict (the first being the input given to the `key` function),
+    - A tuple of operations to apply to the accessed data
+    - An alias for the expression (default to the last token).
+    """
+
+    __tokens__: list[str]
+    __ops__: tuple[Callable[[object], object], ...]
+    _alias: str
+
+    def __repr__(self) -> str:
+        parts: list[str] = []
+        s_parts: list[str] = []
+        for t in self.__tokens__:
+            parts.append(f"field({t!r})")
+            if s_parts:
+                s_parts.append(".")
+            s_parts.append(str(t))
+        symbolic = ".".join(parts) if parts else "<root>"
+        lowered = "".join(s_parts) or "<root>"
+        base = f"Expr({symbolic} -> {lowered})"
+        return f"{base}.alias({self._alias!r})"
+
+    def _to_expr(self, op: Callable[[Any], Any]) -> Self:
+        return self.__class__(
+            self.__tokens__,
+            self.__ops__ + (op,),
+            self._alias,
+        )
+
+    def key(self, name: str) -> Self:
+        """
+        Add a key to the expression.
+
+        Allow to access nested keys in a dict.
+
+        Args:
+            name: The key to access.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> expr = pc.key("a").key("b").key("c")
+        >>> expr.__tokens__
+        ['a', 'b', 'c']
+        >>> data = {"a": {"b": {"c": 42}}}
+        >>> pc.Dict(data).select(expr).unwrap()
+        {'c': 42}
+
+        ```
+        """
+        return self.__class__(
+            self.__tokens__ + [name],
+            self.__ops__,
+            name,
+        )
+
+    def alias(self, name: str) -> Self:
+        return self.__class__(self.__tokens__, self.__ops__, name)
+
+    @property
+    def name(self) -> str:
+        return self._alias
+
+    def apply(self, fn: Callable[[Any], Any]) -> Self:
+        """
+        Applies the given function fn to the data within the current Expr instance
+        """
+
+        def _apply(data: Any) -> Any:
+            return fn(data)
+
+        return self._to_expr(_apply)
+
+
+def key(name: str) -> Expr:
+    """Create an Expr that accesses the given key."""
+    return Expr([name], (), name)
+
+
+def _expr_identity(obj: Any) -> TypeGuard[Expr]:
+    return hasattr(obj, "__tokens__")
+
+
+type IntoExpr = Expr | str
+
+
+def compute_exprs(
+    exprs: Iterable[IntoExpr], data_in: dict[str, Any], data_out: dict[str, Any]
+) -> dict[str, Any]:
+    for e in exprs:
+        if not _expr_identity(e):
+            e = key(e)  # type: ignore
+        current: object = cz.dicttoolz.get_in(e.__tokens__, data_in)
+        for op in e.__ops__:
+            current = op(current)
+        data_out[e.name] = current
+    return data_out

pyochain/_dict/_filters.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from functools import partial
+from typing import TYPE_CHECKING, Any, TypeGuard
+
+import cytoolz as cz
+
+from .._core import MappingWrapper
+
+if TYPE_CHECKING:
+    from ._main import Dict
+
+
+class FilterDict[K, V](MappingWrapper[K, V]):
+    def filter_keys(self, predicate: Callable[[K], bool]) -> Dict[K, V]:
+        """
+        Return a new Dict containing keys that satisfy predicate.
+
+        Args:
+            predicate: Function to determine if a key should be included.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> d = {1: 2, 2: 3, 3: 4, 4: 5}
+        >>> pc.Dict(d).filter_keys(lambda x: x % 2 == 0).unwrap()
+        {2: 3, 4: 5}
+
+        ```
+        """
+        return self.apply(partial(cz.dicttoolz.keyfilter, predicate))
+
+    def filter_values(self, predicate: Callable[[V], bool]) -> Dict[K, V]:
+        """
+        Return a new Dict containing items whose values satisfy predicate.
+
+        Args:
+            predicate: Function to determine if a value should be included.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> d = {1: 2, 2: 3, 3: 4, 4: 5}
+        >>> pc.Dict(d).filter_values(lambda x: x % 2 == 0).unwrap()
+        {1: 2, 3: 4}
+        >>> pc.Dict(d).filter_values(lambda x: not x > 3).unwrap()
+        {1: 2, 2: 3}
+
+        ```
+        """
+        return self.apply(partial(cz.dicttoolz.valfilter, predicate))
+
+    def filter_items(
+        self,
+        predicate: Callable[[tuple[K, V]], bool],
+    ) -> Dict[K, V]:
+        """
+        Filter items by predicate applied to (key, value) tuples.
+
+        Args:
+            predicate: Function to determine if a (key, value) pair should be included.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> def isvalid(item):
+        ...     k, v = item
+        ...     return k % 2 == 0 and v < 4
+        >>> d = pc.Dict({1: 2, 2: 3, 3: 4, 4: 5})
+        >>>
+        >>> d.filter_items(isvalid).unwrap()
+        {2: 3}
+        >>> d.filter_items(lambda kv: not isvalid(kv)).unwrap()
+        {1: 2, 3: 4, 4: 5}
+
+        ```
+        """
+        return self.apply(partial(cz.dicttoolz.itemfilter, predicate))
+
+    def filter_kv(
+        self,
+        predicate: Callable[[K, V], bool],
+    ) -> Dict[K, V]:
+        """
+        Filter items by predicate applied to unpacked (key, value) tuples.
+
+        Args:
+            predicate: Function to determine if a key-value pair should be included.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> def isvalid(key, value):
+        ...     return key % 2 == 0 and value < 4
+        >>> d = pc.Dict({1: 2, 2: 3, 3: 4, 4: 5})
+        >>>
+        >>> d.filter_kv(isvalid).unwrap()
+        {2: 3}
+        >>> d.filter_kv(lambda k, v: not isvalid(k, v)).unwrap()
+        {1: 2, 3: 4, 4: 5}
+
+        ```
+        """
+
+        def _filter_kv(data: dict[K, V]) -> dict[K, V]:
+            def _(kv: tuple[K, V]) -> bool:
+                return predicate(kv[0], kv[1])
+
+            return cz.dicttoolz.itemfilter(_, data)
+
+        return self.apply(_filter_kv)
+
+    def filter_attr[U](self, attr: str, dtype: type[U] = object) -> Dict[K, U]:
+        """
+        Filter values that have a given attribute.
+
+        This does not enforce type checking at runtime for performance considerations.
+        Args:
+            attr: Attribute name to check for.
+            dtype: Optional expected type of the attribute for type hinting.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({"a": "hello", "b": "world", "c": 2, "d": 5}).filter_attr(
+        ...     "capitalize", str
+        ... ).unwrap()
+        {'a': 'hello', 'b': 'world'}
+
+        ```
+        """
+
+        def _filter_attr(data: dict[K, V]) -> dict[K, U]:
+            def has_attr(x: V) -> TypeGuard[U]:
+                return hasattr(x, attr)
+
+            return cz.dicttoolz.valfilter(has_attr, data)
+
+        return self.apply(_filter_attr)
+
+    def filter_type[R](self, typ: type[R]) -> Dict[K, R]:
+        """
+        Filter values by type.
+
+        Args:
+            typ: Type to filter values by.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> data = {"a": "one", "b": "two", "c": 3, "d": 4}
+        >>> pc.Dict(data).filter_type(str).unwrap()
+        {'a': 'one', 'b': 'two'}
+
+        ```
+        """
+
+        def _filter_type(data: dict[K, V]) -> dict[K, R]:
+            def _(x: V) -> TypeGuard[R]:
+                return isinstance(x, typ)
+
+            return cz.dicttoolz.valfilter(_, data)
+
+        return self.apply(_filter_type)
+
+    def filter_callable(self) -> Dict[K, Callable[..., Any]]:
+        """
+        Filter values that are callable.
+        ```python
+        >>> import pyochain as pc
+        >>> def foo():
+        ...     pass
+        >>> data = {1: "one", 2: "two", 3: foo, 4: print}
+        >>> pc.Dict(data).filter_callable().map_values(lambda x: x.__name__).unwrap()
+        {3: 'foo', 4: 'print'}
+
+        ```
+        """
+
+        def _filter_callable(data: dict[K, V]) -> dict[K, Callable[..., Any]]:
+            def _(x: V) -> TypeGuard[Callable[..., Any]]:
+                return callable(x)
+
+            return cz.dicttoolz.valfilter(_, data)
+
+        return self.apply(_filter_callable)
+
+    def filter_subclass[U: type[Any], R](
+        self: FilterDict[K, U], parent: type[R], keep_parent: bool = True
+    ) -> Dict[K, type[R]]:
+        """
+        Filter values that are subclasses of a given parent class.
+
+        Args:
+            parent: Parent class to check against.
+            keep_parent: Whether to include the parent class itself. Defaults to True.
+
+        ```python
+        >>> import pyochain as pc
+        >>> class A:
+        ...     pass
+        >>> class B(A):
+        ...     pass
+        >>> class C:
+        ...     pass
+        >>> def name(cls: type[Any]) -> str:
+        ...     return cls.__name__
+        >>> data = pc.Dict({"first": A, "second": B, "third": C})
+        >>> data.filter_subclass(A).map_values(name).unwrap()
+        {'first': 'A', 'second': 'B'}
+        >>> data.filter_subclass(A, keep_parent=False).map_values(name).unwrap()
+        {'second': 'B'}
+
+        ```
+        """
+
+        def _filter_subclass(data: dict[K, U]) -> dict[K, type[R]]:
+            def _(x: type[Any]) -> TypeGuard[type[R]]:
+                if keep_parent:
+                    return issubclass(x, parent)
+                else:
+                    return issubclass(x, parent) and x is not parent
+
+            return cz.dicttoolz.valfilter(_, data)
+
+        return self.apply(_filter_subclass)
+
+    def intersect_keys(self, *others: Mapping[K, V]) -> Dict[K, V]:
+        """
+        Return a new Dict keeping only keys present in self and all others.
+
+        Args:
+            *others: Other mappings to intersect keys with.
+
+        ```python
+        >>> import pyochain as pc
+        >>> d1 = {"a": 1, "b": 2, "c": 3}
+        >>> d2 = {"b": 10, "c": 20}
+        >>> d3 = {"c": 30}
+        >>> pc.Dict(d1).intersect_keys(d2, d3).unwrap()
+        {'c': 3}
+
+        ```
+        """
+
+        def _intersect_keys(data: dict[K, V]) -> dict[K, V]:
+            self_keys = set(data.keys())
+            for other in others:
+                self_keys.intersection_update(other.keys())
+            return {k: data[k] for k in self_keys}
+
+        return self.apply(_intersect_keys)
+
+    def diff_keys(self, *others: Mapping[K, V]) -> Dict[K, V]:
+        """
+        Return a new Dict keeping only keys present in self but not in others.
+
+        Args:
+            *others: Other mappings to exclude keys from.
+
+        ```python
+        >>> import pyochain as pc
+        >>> d1 = {"a": 1, "b": 2, "c": 3}
+        >>> d2 = {"b": 10, "d": 40}
+        >>> d3 = {"c": 30}
+        >>> pc.Dict(d1).diff_keys(d2, d3).unwrap()
+        {'a': 1}
+
+        ```
+        """
+
+        def _diff_keys(data: dict[K, V]) -> dict[K, V]:
+            self_keys = set(data.keys())
+            for other in others:
+                self_keys.difference_update(other.keys())
+            return {k: data[k] for k in self_keys}
+
+        return self.apply(_diff_keys)