pyochain 0.5.3__py3-none-any.whl

pyochain/__init__.py

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

pyochain/_core/__init__.py

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

pyochain/_core/_format.py

@@ -0,0 +1,34 @@
+from collections.abc import Iterable, Iterator, Mapping
+from pprint import pformat
+from typing import Any, NamedTuple
+
+import cytoolz as cz
+
+
+class Peeked[T](NamedTuple):
+    value: T | tuple[T, ...]
+    sequence: Iterator[T]
+
+
+def peekn[T](data: Iterable[T], n: int) -> Iterator[T]:
+    peeked = Peeked(*cz.itertoolz.peekn(n, data))
+    print(f"Peeked {n} values: {peeked.value}")
+    return peeked.sequence
+
+
+def peek[T](data: Iterable[T]) -> Iterator[T]:
+    peeked = Peeked(*cz.itertoolz.peek(data))
+    print(f"Peeked value: {peeked.value}")
+    return peeked.sequence
+
+
+def dict_repr(
+    v: Mapping[Any, Any],
+    max_items: int = 20,
+    depth: int = 3,
+    width: int = 80,
+    compact: bool = True,
+) -> str:
+    truncated = dict(list(v.items())[:max_items])
+    suffix = "..." if len(v) > max_items else ""
+    return pformat(truncated, depth=depth, width=width, compact=compact) + suffix

pyochain/_core/_main.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable, Iterator, Sequence
+from typing import TYPE_CHECKING, Any, Concatenate, Self
+
+from ._format import dict_repr
+
+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.
+    """
+
+    _inner: T
+
+    __slots__ = ("_inner",)
+
+    def __init__(self, data: T) -> None:
+        self._inner = 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:
+            self.into(pprint, sort_dicts=False)
+        else:
+            self.into(print)
+        return self
+
+    def unwrap(self) -> T:
+        """
+        Return the underlying data.
+
+        This is a terminal operation.
+        """
+        return self._inner
+
+    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)
+
+    def equals_to(self, other: Self | T) -> bool:
+        """
+        Check if two records are equal based on their data.
+
+        Args:
+            other: Another instance or corresponding underlying data 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
+
+        ```
+        """
+        other_data = other.unwrap() if isinstance(other, self.__class__) else other
+        return self.unwrap() == other_data
+
+
+class IterWrapper[T](CommonBase[Iterable[T]]):
+    _inner: Iterable[T]
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.unwrap().__repr__()})"
+
+    def _eager[**P, U](
+        self,
+        factory: Callable[Concatenate[Iterable[T], P], Sequence[U]],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Seq[U]:
+        from .._iter import Seq
+
+        def _(data: Iterable[T]):
+            return Seq(factory(data, *args, **kwargs))
+
+        return self.into(_)
+
+    def _lazy[**P, U](
+        self,
+        factory: Callable[Concatenate[Iterable[T], P], Iterator[U]],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Iter[U]:
+        from .._iter import Iter
+
+        def _(data: Iterable[T]):
+            return Iter(factory(data, *args, **kwargs))
+
+        return self.into(_)
+
+
+class MappingWrapper[K, V](CommonBase[dict[K, V]]):
+    _inner: dict[K, V]
+
+    def __repr__(self) -> str:
+        return f"{self.into(dict_repr)}"
+
+    def _new[KU, VU](self, func: Callable[[dict[K, V]], dict[KU, VU]]) -> Dict[KU, VU]:
+        from .._dict import Dict
+
+        return Dict(func(self.unwrap()))
+
+    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'}
+
+        ```
+        """
+
+        def _(data: dict[K, V]) -> dict[KU, VU]:
+            return func(data, *args, **kwargs)
+
+        return self._new(_)
+
+
+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,38 @@
+from collections.abc import Iterable, Sized
+from typing import Protocol
+
+
+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,3 @@
+from ._main import Dict
+
+__all__ = ["Dict"]

pyochain/_dict/_filters.py

@@ -0,0 +1,268 @@
+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 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._new(partial(cz.dicttoolz.keyfilter, predicate))
+
+    def filter_values(self, predicate: Callable[[V], bool]) -> Dict[K, V]:
+        """
+        Return 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._new(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._new(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._new(_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._new(_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._new(_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._new(_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._new(_filter_subclass)
+
+    def intersect_keys(self, *others: Mapping[K, V]) -> Dict[K, V]:
+        """
+        Keep only keys present in self and all others mappings.
+
+        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._new(_intersect_keys)
+
+    def diff_keys(self, *others: Mapping[K, V]) -> Dict[K, V]:
+        """
+        Keep only keys present in self but not in others mappings.
+
+        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._new(_diff_keys)