pyochain 0.5.3__py3-none-any.whl

pyochain/_iter/_aggregations.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import functools
+import statistics
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING, Literal, NamedTuple
+
+import cytoolz as cz
+import more_itertools as mit
+
+from .._core import IterWrapper
+
+if TYPE_CHECKING:
+    from ._main import Iter
+
+
+class Unzipped[T, V](NamedTuple):
+    first: Iter[T]
+    second: Iter[V]
+
+
+class BaseAgg[T](IterWrapper[T]):
+    def unzip[U, V](self: IterWrapper[tuple[U, V]]) -> Unzipped[U, V]:
+        """
+        Converts an iterator of pairs into a pair of iterators.
+
+        `Iter.unzip()` consumes the iterator of pairs.
+
+        Returns an Unzipped NamedTuple, containing two iterators:
+
+        - 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
+        >>> data = [(1, "a"), (2, "b"), (3, "c")]
+        >>> unzipped = pc.Iter.from_(data).unzip()
+        >>> unzipped.first.into(list)
+        [1, 2, 3]
+        >>> unzipped.second.into(list)
+        ['a', 'b', 'c']
+
+        ```
+        """
+        from ._main import Iter
+
+        def _unzip(data: Iterable[tuple[U, V]]) -> Unzipped[U, V]:
+            d: list[tuple[U, V]] = list(data)
+            return Unzipped(Iter(x[0] for x in d), Iter(x[1] for x in d))
+
+        return self.into(_unzip)
+
+    def reduce(self, func: Callable[[T, T], T]) -> T:
+        """
+        Apply a function of two arguments cumulatively to the items of an iterable, from left to right.
+
+        Args:
+            func: Function to apply cumulatively to the items of the iterable.
+
+        This effectively reduces the iterable to a single value.
+
+        If initial is present, it is placed before the items of the iterable in the calculation.
+
+        It then serves as a default when the iterable is empty.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 3]).reduce(lambda a, b: a + b)
+        6
+
+        ```
+        """
+        return self.into(functools.partial(functools.reduce, func))
+
+    def combination_index(self, r: Iterable[T]) -> int:
+        """
+        Equivalent to list(combinations(iterable, r)).index(element).
+
+        Args:
+            r: The combination to find the index of.
+
+        The subsequences of iterable that are of length r can be ordered lexicographically.
+
+        combination_index computes the index of the first element, without computing the previous combinations.
+
+        ValueError will be raised if the given element isn't one of the combinations of iterable.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_("abcdefg").combination_index("adf")
+        10
+
+        ```
+        """
+        return self.into(functools.partial(mit.combination_index, r))
+
+    def first(self) -> T:
+        """
+        Return the first element.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([9]).first()
+        9
+
+        ```
+        """
+        return self.into(cz.itertoolz.first)
+
+    def second(self) -> T:
+        """
+        Return the second element.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([9, 8]).second()
+        8
+
+        ```
+        """
+        return self.into(cz.itertoolz.second)
+
+    def last(self) -> T:
+        """
+        Return the last element.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([7, 8, 9]).last()
+        9
+
+        ```
+        """
+        return self.into(cz.itertoolz.last)
+
+    def count(self) -> int:
+        """
+        Return the length of the sequence.
+        Like the builtin len but works on lazy sequences.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2]).count()
+        2
+
+        ```
+        """
+        return self.into(cz.itertoolz.count)
+
+    def item(self, index: int) -> T:
+        """
+        Return item at index.
+
+        Args:
+            index: The index of the item to retrieve.
+
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([10, 20]).item(1)
+        20
+
+        ```
+        """
+        return self.into(functools.partial(cz.itertoolz.nth, index))
+
+    def argmax[U](self, key: Callable[[T], U] | None = None) -> int:
+        """
+        Index of the first occurrence of a maximum value in an iterable.
+
+        Args:
+            key: Optional function to determine the value for comparison.
+
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_("abcdefghabcd").argmax()
+        7
+        >>> pc.Iter.from_([0, 1, 2, 3, 3, 2, 1, 0]).argmax()
+        3
+
+        ```
+        For example, identify the best machine learning model:
+        ```python
+        >>> models = pc.Iter.from_(["svm", "random forest", "knn", "naïve bayes"])
+        >>> accuracy = pc.Seq([68, 61, 84, 72])
+        >>> # Most accurate model
+        >>> models.item(accuracy.argmax())
+        'knn'
+        >>>
+        >>> # Best accuracy
+        >>> accuracy.into(max)
+        84
+
+        ```
+        """
+        return self.into(mit.argmax, key=key)
+
+    def argmin[U](self, key: Callable[[T], U] | None = None) -> int:
+        """
+        Index of the first occurrence of a minimum value in an iterable.
+
+        Args:
+            key: Optional function to determine the value for comparison.
+
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_("efghabcdijkl").argmin()
+        4
+        >>> pc.Iter.from_([3, 2, 1, 0, 4, 2, 1, 0]).argmin()
+        3
+
+        ```
+
+        For example, look up a label corresponding to the position of a value that minimizes a cost function:
+        ```python
+        >>> def cost(x):
+        ...     "Days for a wound to heal given a subject's age."
+        ...     return x**2 - 20 * x + 150
+        >>> labels = pc.Iter.from_(["homer", "marge", "bart", "lisa", "maggie"])
+        >>> ages = pc.Seq([35, 30, 10, 9, 1])
+        >>> # Fastest healing family member
+        >>> labels.item(ages.argmin(key=cost))
+        'bart'
+        >>> # Age with fastest healing
+        >>> ages.into(min, key=cost)
+        10
+
+        ```
+        """
+        return self.into(mit.argmin, key=key)
+
+    def sum[U: int | float](self: IterWrapper[U]) -> U | Literal[0]:
+        """
+        Return the sum of the sequence.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 3]).sum()
+        6
+
+        ```
+        """
+        return self.into(sum)
+
+    def min[U: int | float](self: IterWrapper[U]) -> U:
+        """
+        Return the minimum of the sequence.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([3, 1, 2]).min()
+        1
+
+        ```
+        """
+        return self.into(min)
+
+    def max[U: int | float](self: IterWrapper[U]) -> U:
+        """
+        Return the maximum of the sequence.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([3, 1, 2]).max()
+        3
+
+        ```
+        """
+        return self.into(max)
+
+    def mean[U: int | float](self: IterWrapper[U]) -> float:
+        """
+        Return the mean of the sequence.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 3]).mean()
+        2
+
+        ```
+        """
+        return self.into(statistics.mean)
+
+    def median[U: int | float](self: IterWrapper[U]) -> float:
+        """
+        Return the median of the sequence.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 3, 2]).median()
+        2
+
+        ```
+        """
+        return self.into(statistics.median)
+
+    def mode[U: int | float](self: IterWrapper[U]) -> U:
+        """
+        Return the mode of the sequence.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 2, 3]).mode()
+        2
+
+        ```
+        """
+        return self.into(statistics.mode)
+
+    def stdev[U: int | float](
+        self: IterWrapper[U],
+    ) -> float:
+        """
+        Return the standard deviation of the sequence.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 3]).stdev()
+        1.0
+
+        ```
+        """
+        return self.into(statistics.stdev)
+
+    def variance[U: int | float](
+        self: IterWrapper[U],
+    ) -> float:
+        """
+        Return the variance of the sequence.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2, 3, 7, 8]).variance()
+        9.7
+
+        ```
+        """
+        return self.into(statistics.variance)

pyochain/_iter/_booleans.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import overload
+
+import cytoolz as cz
+import more_itertools as mit
+
+from .._core import IterWrapper
+
+
+class BaseBool[T](IterWrapper[T]):
+    def all(self, predicate: Callable[[T], bool] = lambda x: bool(x)) -> bool:
+        """
+        Tests if every element of the iterator matches a predicate.
+
+        `Iter.all()` takes a closure that returns true or false.
+
+        It applies this closure to each element of the iterator, and if they all return true, then so does `Iter.all()`.
+
+        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:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, True]).all()
+        True
+        >>> pc.Iter.from_([]).all()
+        True
+        >>> pc.Iter.from_([1, 0]).all()
+        False
+        >>> def is_even(x: int) -> bool:
+        ...     return x % 2 == 0
+        >>> pc.Iter.from_([2, 4, 6]).all(is_even)
+        True
+
+        ```
+        """
+
+        def _all(data: Iterable[T]) -> bool:
+            return all(predicate(x) for x in data)
+
+        return self.into(_all)
+
+    def any(self, predicate: Callable[[T], bool] = lambda x: bool(x)) -> bool:
+        """
+        Tests if any element of the iterator matches a predicate.
+
+
+        `Iter.any()` takes a closure that returns true or false.
+
+        It applies this closure to each element of the iterator, and if any of them return true, then so does `Iter.any()`.
+
+        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:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([0, 1]).any()
+        True
+        >>> pc.Iter.from_(range(0)).any()
+        False
+        >>> def is_even(x: int) -> bool:
+        ...     return x % 2 == 0
+        >>> pc.Iter.from_([1, 3, 4]).any(is_even)
+        True
+
+        ```
+        """
+
+        def _any(data: Iterable[T]) -> bool:
+            return any(predicate(x) for x in data)
+
+        return self.into(_any)
+
+    def is_distinct(self) -> bool:
+        """
+        Return True if all items are distinct.
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 2]).is_distinct()
+        True
+
+        ```
+        """
+        return self.into(cz.itertoolz.isdistinct)
+
+    def all_equal[U](self, key: Callable[[T], U] | None = None) -> bool:
+        """
+        Return True if all items are equal.
+
+        Args:
+            key: Function to transform items before comparison. Defaults to None.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_([1, 1, 1]).all_equal()
+        True
+
+        ```
+        A function that accepts a single argument and returns a transformed version of each input item can be specified with key:
+        ```python
+        >>> pc.Iter.from_("AaaA").all_equal(key=str.casefold)
+        True
+        >>> pc.Iter.from_([1, 2, 3]).all_equal(key=lambda x: x < 10)
+        True
+
+        ```
+        """
+        return self.into(mit.all_equal, key=key)
+
+    def all_unique[U](self, key: Callable[[T], U] | None = None) -> bool:
+        """
+        Returns True if all the elements of iterable are unique.
+
+        Args:
+            key: Function to transform items before comparison. Defaults to None.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_("ABCB").all_unique()
+        False
+
+        ```
+        If a key function is specified, it will be used to make comparisons.
+        ```python
+        >>> pc.Iter.from_("ABCb").all_unique()
+        True
+        >>> pc.Iter.from_("ABCb").all_unique(str.lower)
+        False
+
+        ```
+        The function returns as soon as the first non-unique element is encountered.
+
+        Iterables with a mix of hashable and unhashable items can be used, but the function will be slower for unhashable items
+
+        """
+        return self.into(mit.all_unique, key=key)
+
+    def is_sorted[U](
+        self,
+        key: Callable[[T], U] | None = None,
+        reverse: bool = False,
+        strict: bool = False,
+    ) -> bool:
+        """
+        Returns True if the items of iterable are in sorted order.
+
+        Args:
+            key: Function to transform items before comparison. Defaults to None.
+            reverse: Whether to check for descending order. Defaults to False.
+            strict: Whether to enforce strict sorting (no equal elements). Defaults to False.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_(["1", "2", "3", "4", "5"]).is_sorted(key=int)
+        True
+        >>> pc.Iter.from_([5, 4, 3, 1, 2]).is_sorted(reverse=True)
+        False
+
+        If strict, tests for strict sorting, that is, returns False if equal elements are found:
+        ```python
+        >>> pc.Iter.from_([1, 2, 2]).is_sorted()
+        True
+        >>> pc.Iter.from_([1, 2, 2]).is_sorted(strict=True)
+        False
+
+        ```
+
+        The function returns False after encountering the first out-of-order item.
+
+        This means it may produce results that differ from the built-in sorted function for objects with unusual comparison dynamics (like math.nan).
+
+        If there are no out-of-order items, the iterable is exhausted.
+        """
+        return self.into(mit.is_sorted, key=key, reverse=reverse, strict=strict)
+
+    @overload
+    def find(
+        self, default: None = None, predicate: Callable[[T], bool] | None = ...
+    ) -> T | None: ...
+    @overload
+    def find(self, default: T, predicate: Callable[[T], bool] | None = ...) -> T: ...
+
+    def find[U](
+        self, default: U = None, predicate: Callable[[T], bool] | None = None
+    ) -> U | T:
+        """
+        Searches for an element of an iterator that satisfies a `predicate`, by:
+
+        - Taking a closure that returns true or false as `predicate` (optional).
+        - Using the identity function if no `predicate` is provided.
+        - Applying this closure to each element of the iterator.
+        - 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.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> def gt_five(x: int) -> bool:
+        ...     return x > 5
+        >>>
+        >>> def gt_nine(x: int) -> bool:
+        ...     return x > 9
+        >>>
+        >>> pc.Iter.from_(range(10)).find()
+        1
+        >>> pc.Iter.from_(range(10)).find(predicate=gt_five)
+        6
+        >>> pc.Iter.from_(range(10)).find(default="missing", predicate=gt_nine)
+        'missing'
+
+        ```
+        """
+        return self.into(mit.first_true, default, predicate)