pyochain 0.5.3__py3-none-any.whl

pyochain/_iter/_dicts.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from typing import TYPE_CHECKING, Any
+
+import cytoolz as cz
+
+from .._core import IterWrapper
+
+if TYPE_CHECKING:
+    from .._dict import Dict
+
+
+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]:
+        """
+        Perform a simultaneous groupby and reduction.
+
+        Args:
+            key: Function to compute the key for grouping.
+            binop: Binary operation to reduce the grouped elements.
+        Example:
+        ```python
+        >>> from collections.abc import Iterable
+        >>> import pyochain as pc
+        >>> from operator import add, mul
+        >>>
+        >>> def is_even(x: int) -> bool:
+        ...     return x % 2 == 0
+        >>>
+        >>> def group_reduce(data: Iterable[int]) -> int:
+        ...     return pc.Iter.from_(data).reduce(add)
+        >>>
+        >>> data = pc.Seq([1, 2, 3, 4, 5])
+        >>> data.iter().reduce_by(is_even, add).unwrap()
+        {False: 9, True: 6}
+        >>> data.iter().group_by(is_even).map_values(group_reduce).unwrap()
+        {False: 9, True: 6}
+
+        ```
+        But the former does not build the intermediate groups, allowing it to operate in much less space.
+
+        This makes it suitable for larger datasets that do not fit comfortably in memory
+
+        Simple Examples:
+        ```python
+        >>> pc.Iter.from_([1, 2, 3, 4, 5]).reduce_by(is_even, add).unwrap()
+        {False: 9, True: 6}
+        >>> pc.Iter.from_([1, 2, 3, 4, 5]).reduce_by(is_even, mul).unwrap()
+        {False: 15, True: 8}
+
+        ```
+        """
+        from .._dict import Dict
+
+        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]]:
+        """
+        Group elements by key function and return a Dict result.
+
+        Args:
+            on: Function to compute the key for grouping.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> names = [
+        ...     "Alice",
+        ...     "Bob",
+        ...     "Charlie",
+        ...     "Dan",
+        ...     "Edith",
+        ...     "Frank",
+        ... ]
+        >>> pc.Iter.from_(names).group_by(len).sort()
+        ... # doctest: +NORMALIZE_WHITESPACE
+        {3: ['Bob', 'Dan'], 5: ['Alice', 'Edith', 'Frank'], 7: ['Charlie']}
+        >>>
+        >>> iseven = lambda x: x % 2 == 0
+        >>> pc.Iter.from_([1, 2, 3, 4, 5, 6, 7, 8]).group_by(iseven)
+        ... # doctest: +NORMALIZE_WHITESPACE
+        {False: [1, 3, 5, 7], True: [2, 4, 6, 8]}
+
+        ```
+        Non-callable keys imply grouping on a member.
+        ```python
+        >>> data = [
+        ...     {"name": "Alice", "gender": "F"},
+        ...     {"name": "Bob", "gender": "M"},
+        ...     {"name": "Charlie", "gender": "M"},
+        ... ]
+        >>> pc.Iter.from_(data).group_by("gender").sort()
+        ... # doctest: +NORMALIZE_WHITESPACE
+        {'F': [{'gender': 'F', 'name': 'Alice'}],
+        'M': [{'gender': 'M', 'name': 'Bob'}, {'gender': 'M', 'name': 'Charlie'}]}
+
+        ```
+        """
+        from .._dict import Dict
+
+        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]:
+        """
+        Find number of occurrences of each value in the iterable.
+        ```python
+        >>> import pyochain as pc
+        >>> data = ["cat", "cat", "ox", "pig", "pig", "cat"]
+        >>> pc.Iter.from_(data).frequencies().unwrap()
+        {'cat': 3, 'ox': 1, 'pig': 2}
+
+        ```
+        """
+        from .._dict import Dict
+
+        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]:
+        """
+        Count elements of a collection by a key function.
+
+        Args:
+            key: Function to compute the key for counting.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_(["cat", "mouse", "dog"]).count_by(len).unwrap()
+        {3: 2, 5: 1}
+        >>> def iseven(x):
+        ...     return x % 2 == 0
+        >>> pc.Iter.from_([1, 2, 3]).count_by(iseven).unwrap()
+        {False: 2, True: 1}
+
+        ```
+        """
+        from .._dict import Dict
+
+        def _count_by(data: Iterable[T]) -> Dict[K, int]:
+            return Dict(cz.recipes.countby(key, data))
+
+        return self.into(_count_by)
+
+    def to_records[U: Sequence[Any]](self: BaseDict[U]) -> Dict[Any, Any]:
+        """
+        Transform an iterable of nested sequences into a nested dictionary.
+
+        - Each inner sequence represents a path to a value in the dictionary.
+        - The last element of each sequence is treated as the value
+        - All preceding elements are treated as keys leading to that value.
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> arrays = [["a", "b", 1], ["a", "c", 2], ["d", 3]]
+        >>> pc.Seq(arrays).to_records().unwrap()
+        {'a': {'b': 1, 'c': 2}, 'd': 3}
+
+        ```
+        """
+        from .._dict import Dict
+
+        def _from_nested(
+            arrays: Iterable[Sequence[Any]], parent: dict[Any, Any] | None = None
+        ) -> dict[Any, Any]:
+            """from dictutils.pivot"""
+            d: dict[Any, Any] = parent or {}
+            for arr in arrays:
+                if len(arr) >= 2:
+                    head, *tail = arr
+                    if len(tail) == 1:
+                        d[head] = tail[0]
+                    else:
+                        d[head] = _from_nested([tail], d.get(head, {}))
+            return d
+
+        return Dict(self.into(_from_nested))

pyochain/_iter/_eager.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from functools import partial
+from typing import TYPE_CHECKING, Any
+
+import cytoolz as cz
+
+from .._core import IterWrapper, SupportsRichComparison
+
+if TYPE_CHECKING:
+    from ._main import Seq
+
+
+class BaseEager[T](IterWrapper[T]):
+    def sort[U: SupportsRichComparison[Any]](
+        self: BaseEager[U], reverse: bool = False, key: Callable[[U], Any] | None = None
+    ) -> Seq[U]:
+        """
+        Sort the elements of the sequence.
+
+        Note:
+            This method must consume the entire iterable to perform the sort.
+            The result is a new iterable over the sorted sequence.
+
+        Args:
+            reverse: Whether to sort in descending order. Defaults to False.
+            key: Function to extract a comparison key from each element. Defaults to None.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([3, 1, 2]).sort().into(list)
+        [1, 2, 3]
+
+        ```
+        """
+
+        def _sort(data: Iterable[U]) -> list[U]:
+            return sorted(data, reverse=reverse, key=key)
+
+        return self._eager(_sort)
+
+    def tail(self, n: int) -> Seq[T]:
+        """
+        Return a tuple of the last n elements.
+
+        Args:
+            n: Number of elements to return.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 3]).tail(2).unwrap()
+        (2, 3)
+
+        ```
+        """
+        return self._eager(partial(cz.itertoolz.tail, n))
+
+    def top_n(self, n: int, key: Callable[[T], Any] | None = None) -> Seq[T]:
+        """
+        Return a tuple of the top-n items according to key.
+
+        Args:
+            n: Number of top elements to return.
+            key: Function to extract a comparison key from each element. Defaults to None.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 3, 2]).top_n(2).unwrap()
+        (3, 2)
+
+        ```
+        """
+        return self._eager(partial(cz.itertoolz.topk, n, key=key))
+
+    def union(self, *others: Iterable[T]) -> Seq[T]:
+        """
+        Return the union of this iterable and 'others'.
+
+        Note:
+            This method consumes inner data and removes duplicates.
+
+        Args:
+            *others: Other iterables to include in the union.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 2]).union([2, 3], [4]).iter().sort().unwrap()
+        [1, 2, 3, 4]
+
+        ```
+        """
+
+        def _union(data: Iterable[T]) -> list[T]:
+            return list(set(data).union(*others))
+
+        return self._eager(_union)
+
+    def intersection(self, *others: Iterable[T]) -> Seq[T]:
+        """
+        Return the elements common to this iterable and 'others'.
+
+        Note:
+            This method consumes inner data, unsorts it, and removes duplicates.
+
+        Args:
+            *others: Other iterables to intersect with.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 2]).intersection([2, 3], [2]).unwrap()
+        [2]
+
+        ```
+        """
+
+        def _intersection(data: Iterable[T]) -> list[T]:
+            return list(set(data).intersection(*others))
+
+        return self._eager(_intersection)
+
+    def diff_unique(self, *others: Iterable[T]) -> Seq[T]:
+        """
+        Return the difference of this iterable and 'others'.
+        (Elements in 'self' but not in 'others').
+
+        Note:
+            This method consumes inner data, unsorts it, and removes duplicates.
+
+        Args:
+            *others: Other iterables to subtract from this iterable.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 2]).diff_unique([2, 3]).unwrap()
+        [1]
+
+        ```
+        """
+
+        def _difference(data: Iterable[T]) -> list[T]:
+            return list(set(data).difference(*others))
+
+        return self._eager(_difference)
+
+    def diff_symmetric(self, *others: Iterable[T]) -> Seq[T]:
+        """
+        Return the symmetric difference (XOR) of this iterable and 'others'.
+
+        Note:
+            This method consumes inner data, unsorts it, and removes duplicates.
+
+        Args:
+            *others: Other iterables to compute the symmetric difference with.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 2]).diff_symmetric([2, 3]).iter().sort().unwrap()
+        [1, 3]
+        >>> pc.Iter.from_([1, 2, 3]).diff_symmetric([3, 4, 5]).iter().sort().unwrap()
+        [1, 2, 4, 5]
+
+        ```
+        """
+
+        def _symmetric_difference(data: Iterable[T]) -> list[T]:
+            return list(set(data).symmetric_difference(*others))
+
+        return self._eager(_symmetric_difference)
+
+    def most_common(self, n: int | None = None) -> Seq[tuple[T, int]]:
+        """
+        Return the n most common elements and their counts.
+
+        If n is None, then all elements are returned.
+
+        Args:
+            n: Number of most common elements to return. Defaults to None (all elements).
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 1, 2, 3, 3, 3]).most_common(2).unwrap()
+        [(3, 3), (1, 2)]
+
+        ```
+        """
+        from collections import Counter
+
+        def _most_common(data: Iterable[T]) -> list[tuple[T, int]]:
+            return Counter(data).most_common(n)
+
+        return self._eager(_most_common)
+
+    def rearrange[U: Sequence[Any]](self: BaseEager[U], *indices: int) -> Seq[list[U]]:
+        """
+        Rearrange elements in a given list of arrays by order indices.
+
+        The last element (value) always remains in place.
+
+        Args:
+            order: List of indices specifying new order of keys
+
+
+        Raises:
+            IndexError: If any index in order is out of range for the row
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> data = pc.Seq([["A", "X", 1], ["A", "Y", 2], ["B", "X", 3], ["B", "Y", 4]])
+        >>> data.rearrange(1, 0).unwrap()
+        [['X', 'A', 1], ['Y', 'A', 2], ['X', 'B', 3], ['Y', 'B', 4]]
+
+        ```
+        """
+
+        def _rearrange(in_arrs: Iterable[U]) -> list[list[U]]:
+            """from dictutils.pivot"""
+            order = indices
+            out: list[list[U]] = []
+            for arr in in_arrs:
+                max_key_index: int = len(arr) - 2
+                for i in order:
+                    if i < 0 or i > max_key_index:
+                        raise IndexError(
+                            f"order index {i} out of range for row with {max_key_index + 1} keys"
+                        )
+
+                out.append([arr[i] for i in order] + [arr[-1]])
+
+            return out
+
+        return self._eager(_rearrange)