pyochain 0.5.1__tar.gz → 0.5.2__tar.gz

{pyochain-0.5.1 → pyochain-0.5.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: pyochain
-Version: 0.5.1
-Summary: Add your description here
+Version: 0.5.2
+Summary: Method chaining for iterables and dictionaries in Python.
 Requires-Dist: cytoolz>=1.0.1
 Requires-Dist: more-itertools>=10.8.0
 Requires-Dist: rolling>=0.5.0
@@ -33,7 +33,7 @@ The full API reference can be found at:
 
 * **Declarative over Imperative:** Replace explicit `for` and `while` loops with sequences of high-level operations (map, filter, group, join...).
 * **Fluent Chaining:** Each method transforms the data and returns a new wrapper instance, allowing for seamless chaining.
-* **Lazy and Eager:** `Iter` operates lazily for efficiency on large or infinite sequences, while `Seq` represents materialized collections for eager operations.
+* **Lazy and Eager:** `Iter` operates lazily for efficiency on large or infinite sequences, while `Seq` represents materialized sequences for eager operations.
 * **100% Type-safe:** Extensive use of generics and overloads ensures type safety and improves developer experience.
 * **Documentation-first:** Each method is thoroughly documented with clear explanations, and usage examples. Before any commit is made, each docstring is automatically tested to ensure accuracy. This also allows for a convenient experience in IDEs, where developers can easily access documentation with a simple hover of the mouse.
 * **Functional paradigm:** Design encourages building complex data transformations by composing simple, reusable functions on known buildings blocks, rather than implementing customs classes each time.
@@ -57,7 +57,7 @@ Provides a vast array of methods for transformation, filtering, aggregation, joi
 
 #### `Seq[T]`
 
-Wraps a Python `Collection` (`list`, `tuple`, `set`...), and represents **eagerly** evaluated data.
+Wraps a Python `Sequence` (`list`, `tuple`...), and represents **eagerly** evaluated data.
 
 Exposes a subset of the `Iter` methods who operate on the full dataset (e.g., `sort`, `union`) or who aggregate it.
 
@@ -122,8 +122,6 @@ Each method and class make extensive use of generics, type hints, and overloads
 
 Since there's much less need for intermediate variables, the developper don't have to annotate them as much, whilst still keeping a type-safe codebase.
 
-Target: modern Python 3.13 syntax (PEP 695 generics, updated collections.abc types).
-
 ### Expressions for Dict ``pyochain.key``
 
 Compute new fields from existing nested data with key() and Expr.apply(), either selecting a new dict or merging into the root.

{pyochain-0.5.1 → pyochain-0.5.2}/README.md

@@ -23,7 +23,7 @@ The full API reference can be found at:
 
 * **Declarative over Imperative:** Replace explicit `for` and `while` loops with sequences of high-level operations (map, filter, group, join...).
 * **Fluent Chaining:** Each method transforms the data and returns a new wrapper instance, allowing for seamless chaining.
-* **Lazy and Eager:** `Iter` operates lazily for efficiency on large or infinite sequences, while `Seq` represents materialized collections for eager operations.
+* **Lazy and Eager:** `Iter` operates lazily for efficiency on large or infinite sequences, while `Seq` represents materialized sequences for eager operations.
 * **100% Type-safe:** Extensive use of generics and overloads ensures type safety and improves developer experience.
 * **Documentation-first:** Each method is thoroughly documented with clear explanations, and usage examples. Before any commit is made, each docstring is automatically tested to ensure accuracy. This also allows for a convenient experience in IDEs, where developers can easily access documentation with a simple hover of the mouse.
 * **Functional paradigm:** Design encourages building complex data transformations by composing simple, reusable functions on known buildings blocks, rather than implementing customs classes each time.
@@ -47,7 +47,7 @@ Provides a vast array of methods for transformation, filtering, aggregation, joi
 
 #### `Seq[T]`
 
-Wraps a Python `Collection` (`list`, `tuple`, `set`...), and represents **eagerly** evaluated data.
+Wraps a Python `Sequence` (`list`, `tuple`...), and represents **eagerly** evaluated data.
 
 Exposes a subset of the `Iter` methods who operate on the full dataset (e.g., `sort`, `union`) or who aggregate it.
 
@@ -112,8 +112,6 @@ Each method and class make extensive use of generics, type hints, and overloads
 
 Since there's much less need for intermediate variables, the developper don't have to annotate them as much, whilst still keeping a type-safe codebase.
 
-Target: modern Python 3.13 syntax (PEP 695 generics, updated collections.abc types).
-
 ### Expressions for Dict ``pyochain.key``
 
 Compute new fields from existing nested data with key() and Expr.apply(), either selecting a new dict or merging into the root.

{pyochain-0.5.1 → pyochain-0.5.2}/pyproject.toml

@@ -1,15 +1,14 @@
 [project]
-description     = "Add your description here"
+description     = "Method chaining for iterables and dictionaries in Python."
 name            = "pyochain"
 readme          = "README.md"
 requires-python = ">=3.12"
-version         = "0.5.1"
+version         = "0.5.2"
 
 dependencies = ["cytoolz>=1.0.1", "more-itertools>=10.8.0", "rolling>=0.5.0"]
 
 [dependency-groups]
 dev = [
-    "cytoolz-stubs",
     "doctester",
     "griffe>=1.14.0",
     "mkdocs>=1.6.1",
@@ -21,13 +20,14 @@ dev = [
     "polars>=1.33.1",
     "ruff>=0.14.1",
     "rolling @ git+https://github.com/OutSquareCapital/rolling.git@add-type-stubs",
+    "cytoolz-stubs",
 ]
 
 [tool.ruff.format]
 docstring-code-format = true
 
 [tool.uv.sources]
-cytoolz-stubs = { git = "https://github.com/py-stubs/cytoolz-stubs.git" }
+cytoolz-stubs = { git = "https://github.com/OutSquareCapital/cytoolz-stubs.git" }
 doctester     = { git = "https://github.com/OutSquareCapital/doctester.git" }
 
 [build-system]

{pyochain-0.5.1 → pyochain-0.5.2}/src/pyochain/_core/_main.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from collections.abc import Callable, Collection, Iterable, Iterator
+from collections.abc import Callable, Iterable, Iterator, Sequence
 from typing import TYPE_CHECKING, Any, Concatenate, Self
 
 if TYPE_CHECKING:
@@ -53,9 +53,9 @@ class CommonBase[T](ABC, Pipeable):
         from pprint import pprint
 
         if pretty:
-            pprint(self.unwrap(), sort_dicts=False)
+            self.into(pprint, sort_dicts=False)
         else:
-            print(self.unwrap())
+            self.into(print)
         return self
 
     def unwrap(self) -> T:
@@ -90,49 +90,34 @@ class CommonBase[T](ABC, Pipeable):
 class IterWrapper[T](CommonBase[Iterable[T]]):
     _data: Iterable[T]
 
-    def apply[**P, R](
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.unwrap().__repr__()})"
+
+    def _eager[**P, U](
         self,
-        func: Callable[Concatenate[Iterable[T], P], Iterator[R]],
+        factory: Callable[Concatenate[Iterable[T], P], Sequence[U]],
         *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.
+    ) -> Seq[U]:
+        from .._iter import Seq
 
-        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
+        def _(data: Iterable[T]):
+            return Seq(factory(data, *args, **kwargs))
 
-        return Iter(self.into(func, *args, **kwargs))
+        return self.into(_)
 
-    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]
+    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
 
-        ```
-        """
-        from .._iter import Seq
+        def _(data: Iterable[T]):
+            return Iter(factory(data, *args, **kwargs))
 
-        return Seq(self.into(factory))
+        return self.into(_)
 
 
 class MappingWrapper[K, V](CommonBase[dict[K, V]]):
@@ -147,6 +132,7 @@ class MappingWrapper[K, V](CommonBase[dict[K, V]]):
         """
         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.

{pyochain-0.5.1 → pyochain-0.5.2}/src/pyochain/_dict/_exprs.py

@@ -17,6 +17,7 @@ class Expr(Pipeable):
     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).

{pyochain-0.5.1 → pyochain-0.5.2}/src/pyochain/_dict/_filters.py

@@ -112,6 +112,7 @@ class FilterDict[K, V](MappingWrapper[K, V]):
         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.

{pyochain-0.5.1 → pyochain-0.5.2}/src/pyochain/_dict/_groups.py

@@ -143,8 +143,7 @@ class GroupsDict[K, V](MappingWrapper[K, V]):
         ...     agg_func=lambda d: d.iter_keys().count(),
         ... ).unwrap()
         {'A': 2, 'B': 1}
-        >>>
-        >>> # --- Exemple 2: Agrégation plus complexe ---
+        >>> # Second example
         >>> sales_data = {
         ...     "store_1": "Electronics",
         ...     "store_2": "Groceries",

{pyochain-0.5.1 → pyochain-0.5.2}/src/pyochain/_dict/_iter.py

@@ -43,7 +43,7 @@ class IterDict[K, V](MappingWrapper[K, V]):
 
         def _itr(data: Mapping[K, Iterable[U]]) -> dict[K, R]:
             def _(v: Iterable[U]) -> R:
-                return func(Iter.from_(v), *args, **kwargs)
+                return func(Iter(iter(v)), *args, **kwargs)
 
             return cz.dicttoolz.valmap(_, data)
 
@@ -61,7 +61,10 @@ class IterDict[K, V](MappingWrapper[K, V]):
         """
         from .._iter import Iter
 
-        return Iter.from_(self.unwrap().keys())
+        def _keys(data: dict[K, V]) -> Iter[K]:
+            return Iter(iter(data.keys()))
+
+        return self.into(_keys)
 
     def iter_values(self) -> Iter[V]:
         """
@@ -75,7 +78,10 @@ class IterDict[K, V](MappingWrapper[K, V]):
         """
         from .._iter import Iter
 
-        return Iter.from_(self.unwrap().values())
+        def _values(data: dict[K, V]) -> Iter[V]:
+            return Iter(iter(data.values()))
+
+        return self.into(_values)
 
     def iter_items(self) -> Iter[tuple[K, V]]:
         """
@@ -89,4 +95,7 @@ class IterDict[K, V](MappingWrapper[K, V]):
         """
         from .._iter import Iter
 
-        return Iter.from_(self.unwrap().items())
+        def _items(data: dict[K, V]) -> Iter[tuple[K, V]]:
+            return Iter(iter(data.items()))
+
+        return self.into(_items)

{pyochain-0.5.1 → pyochain-0.5.2}/src/pyochain/_dict/_main.py

@@ -300,8 +300,5 @@ class Dict[K, V](
 
         ```
         """
-        return (
-            self.unwrap() == other.unwrap()
-            if isinstance(other, Dict)
-            else self.unwrap() == other
-        )
+        other_data = other.unwrap() if isinstance(other, Dict) else other
+        return self.unwrap() == other_data

{pyochain-0.5.1 → pyochain-0.5.2}/src/pyochain/_dict/_process.py

@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING, Any, Concatenate
 
 import cytoolz as cz
 
-from .._core import MappingWrapper
+from .._core import MappingWrapper, SupportsRichComparison
 
 if TYPE_CHECKING:
     from ._main import Dict
@@ -169,3 +169,24 @@ class ProcessDict[K, V](MappingWrapper[K, V]):
             return dict(sorted(data.items(), reverse=reverse))
 
         return self.apply(_sort)
+
+    def sort_values[U: SupportsRichComparison[Any]](
+        self: ProcessDict[K, U], reverse: bool = False
+    ) -> Dict[K, U]:
+        """
+        Sort the dictionary by its values and return a new Dict.
+
+        Args:
+            reverse: Whether to sort in descending order. Defaults to False.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Dict({"a": 2, "b": 1}).sort_values().unwrap()
+        {'b': 1, 'a': 2}
+
+        ```
+        """
+
+        def _sort_values(data: dict[K, U]) -> dict[K, U]:
+            return dict(sorted(data.items(), key=lambda item: item[1], reverse=reverse))
+
+        return self.apply(_sort_values)

{pyochain-0.5.1 → pyochain-0.5.2}/src/pyochain/_iter/_aggregations.py

@@ -30,6 +30,7 @@ class BaseAgg[T](IterWrapper[T]):
 
         - one from the left elements of the pairs
         - one from the right elements.
+
         This function is, in some sense, the opposite of zip.
         ```python
         >>> import pyochain as pc

{pyochain-0.5.1 → pyochain-0.5.2}/src/pyochain/_iter/_booleans.py

@@ -21,6 +21,7 @@ class BaseBool[T](IterWrapper[T]):
         If any of them return false, it returns false.
 
         An empty iterator returns true.
+
         Args:
             predicate: Function to evaluate each item. Defaults to checking truthiness.
         Example:
@@ -57,6 +58,7 @@ class BaseBool[T](IterWrapper[T]):
         If they all return false, it returns false.
 
         An empty iterator returns false.
+
         Args:
             predicate: Function to evaluate each item. Defaults to checking truthiness.
         Example:
@@ -200,6 +202,7 @@ class BaseBool[T](IterWrapper[T]):
         - Returning the first element that satisfies the `predicate`.
 
         If all the elements return false, `Iter.find()` returns the default value.
+
         Args:
             default: Value to return if no element satisfies the predicate. Defaults to None.
             predicate: Function to evaluate each item. Defaults to checking truthiness.

pyochain-0.5.1/src/pyochain/_iter/_groups.py → pyochain-0.5.2/src/pyochain/_iter/_dicts.py

@@ -1,20 +1,73 @@
 from __future__ import annotations
 
-from collections.abc import Callable, Iterable, Iterator
-from functools import partial
-from typing import TYPE_CHECKING, Any, overload
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING
 
 import cytoolz as cz
-import more_itertools as mit
 
 from .._core import IterWrapper
 
 if TYPE_CHECKING:
     from .._dict import Dict
-    from ._main import Iter
 
 
-class BaseGroups[T](IterWrapper[T]):
+class BaseDict[T](IterWrapper[T]):
+    def with_keys[K](self, keys: Iterable[K]) -> Dict[K, T]:
+        """
+        Create a Dict by zipping the iterable with keys.
+
+        Args:
+            keys: Iterable of keys to pair with the values.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> keys = ["a", "b", "c"]
+        >>> values = [1, 2, 3]
+        >>> pc.Iter.from_(values).with_keys(keys).unwrap()
+        {'a': 1, 'b': 2, 'c': 3}
+        >>> # This is equivalent to:
+        >>> pc.Iter.from_(keys).zip(values).pipe(
+        ...     lambda x: pc.Dict(x.into(dict)).unwrap()
+        ... )
+        {'a': 1, 'b': 2, 'c': 3}
+
+        ```
+        """
+        from .._dict import Dict
+
+        def _with_keys(data: Iterable[T]) -> Dict[K, T]:
+            return Dict(dict(zip(keys, data)))
+
+        return self.into(_with_keys)
+
+    def with_values[V](self, values: Iterable[V]) -> Dict[T, V]:
+        """
+        Create a Dict by zipping the iterable with values.
+
+        Args:
+            values: Iterable of values to pair with the keys.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> keys = [1, 2, 3]
+        >>> values = ["a", "b", "c"]
+        >>> pc.Iter.from_(keys).with_values(values).unwrap()
+        {1: 'a', 2: 'b', 3: 'c'}
+        >>> # This is equivalent to:
+        >>> pc.Iter.from_(keys).zip(values).pipe(
+        ...     lambda x: pc.Dict(x.into(dict)).unwrap()
+        ... )
+        {1: 'a', 2: 'b', 3: 'c'}
+
+        ```
+        """
+        from .._dict import Dict
+
+        def _with_values(data: Iterable[T]) -> Dict[T, V]:
+            return Dict(dict(zip(data, values)))
+
+        return self.into(_with_values)
+
     def reduce_by[K](
         self, key: Callable[[T], K], binop: Callable[[T, T], T]
     ) -> Dict[K, T]:
@@ -58,7 +111,10 @@ class BaseGroups[T](IterWrapper[T]):
         """
         from .._dict import Dict
 
-        return Dict(self.into(partial(cz.itertoolz.reduceby, key, binop)))
+        def _reduce_by(data: Iterable[T]) -> Dict[K, T]:
+            return Dict(cz.itertoolz.reduceby(key, binop, data))
+
+        return self.into(_reduce_by)
 
     def group_by[K](self, on: Callable[[T], K]) -> Dict[K, list[T]]:
         """
@@ -117,7 +173,10 @@ class BaseGroups[T](IterWrapper[T]):
         """
         from .._dict import Dict
 
-        return Dict(self.into(partial(cz.itertoolz.groupby, on)))
+        def _group_by(data: Iterable[T]) -> Dict[K, list[T]]:
+            return Dict(cz.itertoolz.groupby(on, data))
+
+        return self.into(_group_by)
 
     def frequencies(self) -> Dict[T, int]:
         """
@@ -132,7 +191,10 @@ class BaseGroups[T](IterWrapper[T]):
         """
         from .._dict import Dict
 
-        return Dict(self.into(cz.itertoolz.frequencies))
+        def _frequencies(data: Iterable[T]) -> Dict[T, int]:
+            return Dict(cz.itertoolz.frequencies(data))
+
+        return self.into(_frequencies)
 
     def count_by[K](self, key: Callable[[T], K]) -> Dict[K, int]:
         """
@@ -154,111 +216,7 @@ class BaseGroups[T](IterWrapper[T]):
         """
         from .._dict import Dict
 
-        return Dict(self.into(partial(cz.recipes.countby, key)))
-
-    @overload
-    def group_by_transform(
-        self,
-        keyfunc: None = None,
-        valuefunc: None = None,
-        reducefunc: None = None,
-    ) -> Iter[tuple[T, Iterator[T]]]: ...
-    @overload
-    def group_by_transform[U](
-        self,
-        keyfunc: Callable[[T], U],
-        valuefunc: None,
-        reducefunc: None,
-    ) -> Iter[tuple[U, Iterator[T]]]: ...
-    @overload
-    def group_by_transform[V](
-        self,
-        keyfunc: None,
-        valuefunc: Callable[[T], V],
-        reducefunc: None,
-    ) -> Iter[tuple[T, Iterator[V]]]: ...
-    @overload
-    def group_by_transform[U, V](
-        self,
-        keyfunc: Callable[[T], U],
-        valuefunc: Callable[[T], V],
-        reducefunc: None,
-    ) -> Iter[tuple[U, Iterator[V]]]: ...
-    @overload
-    def group_by_transform[W](
-        self,
-        keyfunc: None,
-        valuefunc: None,
-        reducefunc: Callable[[Iterator[T]], W],
-    ) -> Iter[tuple[T, W]]: ...
-    @overload
-    def group_by_transform[U, W](
-        self,
-        keyfunc: Callable[[T], U],
-        valuefunc: None,
-        reducefunc: Callable[[Iterator[T]], W],
-    ) -> Iter[tuple[U, W]]: ...
-    @overload
-    def group_by_transform[V, W](
-        self,
-        keyfunc: None,
-        valuefunc: Callable[[T], V],
-        reducefunc: Callable[[Iterator[V]], W],
-    ) -> Iter[tuple[T, W]]: ...
-    @overload
-    def group_by_transform[U, V, W](
-        self,
-        keyfunc: Callable[[T], U],
-        valuefunc: Callable[[T], V],
-        reducefunc: Callable[[Iterator[V]], W],
-    ) -> Iter[tuple[U, W]]: ...
-    def group_by_transform[U, V](
-        self,
-        keyfunc: Callable[[T], U] | None = None,
-        valuefunc: Callable[[T], V] | None = None,
-        reducefunc: Any = None,
-    ) -> Iter[tuple[Any, ...]]:
-        """
-        An extension of itertools.groupby that can apply transformations to the grouped data.
-
-        Args:
-            keyfunc: Function to compute the key for grouping. Defaults to None.
-            valuefunc: Function to transform individual items after grouping. Defaults to None.
-            reducefunc: Function to transform each group of items. Defaults to None.
-
-        Example:
-        ```python
-        >>> import pyochain as pc
-        >>> data = pc.Iter.from_("aAAbBBcCC")
-        >>> data.group_by_transform(
-        ...     lambda k: k.upper(), lambda v: v.lower(), lambda g: "".join(g)
-        ... ).into(list)
-        [('A', 'aaa'), ('B', 'bbb'), ('C', 'ccc')]
-
-        ```
-        Each optional argument defaults to an identity function if not specified.
-
-        group_by_transform is useful when grouping elements of an iterable using a separate iterable as the key.
-
-        To do this, zip the iterables and pass a keyfunc that extracts the first element and a valuefunc that extracts the second element:
-
-        Note that the order of items in the iterable is significant.
-
-        Only adjacent items are grouped together, so if you don't want any duplicate groups, you should sort the iterable by the key function.
-
-        Example:
-        ```python
-        >>> from operator import itemgetter
-        >>> data = pc.Iter.from_([0, 0, 1, 1, 1, 2, 2, 2, 3])
-        >>> data.zip("abcdefghi").group_by_transform(itemgetter(0), itemgetter(1)).map(
-        ...     lambda kv: (kv[0], "".join(kv[1]))
-        ... ).into(list)
-        [(0, 'ab'), (1, 'cde'), (2, 'fgh'), (3, 'i')]
-
-        ```
-        """
-
-        def _group_by_transform(data: Iterable[T]) -> Iterator[tuple[Any, ...]]:
-            return mit.groupby_transform(data, keyfunc, valuefunc, reducefunc)
+        def _count_by(data: Iterable[T]) -> Dict[K, int]:
+            return Dict(cz.recipes.countby(key, data))
 
-        return self.apply(_group_by_transform)
+        return self.into(_count_by)