pyochain 0.5.0__py3-none-any.whl

pyochain/_iter/_aggregations.py

@@ -0,0 +1,323 @@
+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,224 @@
+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)

pyochain/_iter/_constructors.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import itertools
+from collections.abc import Callable, Iterable, Iterator
+from typing import TYPE_CHECKING
+
+import cytoolz as cz
+
+if TYPE_CHECKING:
+    from ._main import Iter
+
+
+class IterConstructors:
+    @staticmethod
+    def from_count(start: int = 0, step: int = 1) -> Iter[int]:
+        """
+        Create an infinite iterator of evenly spaced values.
+
+        **Warning** ⚠️
+            This creates an infinite iterator.
+            Be sure to use `Iter.take()` or `Iter.slice()` to limit the number of items taken.
+
+        Args:
+            start: Starting value of the sequence. Defaults to 0.
+            step: Difference between consecutive values. Defaults to 1.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_count(10, 2).take(3).into(list)
+        [10, 12, 14]
+
+        ```
+        """
+        from ._main import Iter
+
+        return Iter(itertools.count(start, step))
+
+    @staticmethod
+    def from_func[U](func: Callable[[U], U], input: U) -> Iter[U]:
+        """
+        Create an infinite iterator by repeatedly applying a function on an original input.
+
+        **Warning** ⚠️
+            This creates an infinite iterator.
+            Be sure to use `Iter.take()` or `Iter.slice()` to limit the number of items taken.
+
+        Args:
+            func: Function to apply repeatedly.
+            input: Initial value to start the iteration.
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Iter.from_func(lambda x: x + 1, 0).take(3).into(list)
+        [0, 1, 2]
+
+        ```
+        """
+        from ._main import Iter
+
+        return Iter(cz.itertoolz.iterate(func, input))
+
+    @staticmethod
+    def from_[U](data: Iterable[U]) -> Iter[U]:
+        """
+        Create an iterator from any Iterable.
+
+        - An Iterable is any object capable of returning its members one at a time, permitting it to be iterated over in a for-loop.
+        - An Iterator is an object representing a stream of data; returned by calling `iter()` on an Iterable.
+        - Once an Iterator is exhausted, it cannot be reused or reset.
+
+        If you need to reuse the data, consider collecting it into a list first with `.collect()`.
+
+        In general, avoid intermediate references when dealing with lazy iterators, and prioritize method chaining instead.
+        Args:
+            data: Iterable to convert into an iterator.
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> data: tuple[int, ...] = (1, 2, 3)
+        >>> iterator = pc.Iter.from_(data)
+        >>> iterator.unwrap().__class__.__name__
+        'tuple_iterator'
+        >>> mapped = iterator.map(lambda x: x * 2)
+        >>> mapped.unwrap().__class__.__name__
+        'map'
+        >>> mapped.collect(tuple).unwrap()
+        (2, 4, 6)
+        >>> # iterator is now exhausted
+        >>> iterator.collect().unwrap()
+        []
+
+        ```
+        """
+        from ._main import Iter
+
+        return Iter(iter(data))
+
+    @staticmethod
+    def unfold[S, V](seed: S, generator: Callable[[S], tuple[V, S] | None]) -> Iter[V]:
+        """
+        Create an iterator by repeatedly applying a generator function to an initial state.
+
+        The `generator` function takes the current state and must return:
+            - A tuple `(value, new_state)` to emit the `value` and continue with the `new_state`.
+            - `None` to stop the generation.
+
+        This is functionally equivalent to a state-based `while` loop.
+
+        **Warning** ⚠️
+            If the `generator` function never returns `None`, it creates an infinite iterator.
+            Be sure to use `Iter.take()` or `Iter.slice()` to limit the number of items taken if necessary.
+
+        Args:
+            seed: Initial state for the generator.
+            generator: Function that generates the next value and state.
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> # Example 1: Simple counter up to 5
+        >>> def counter_generator(state: int) -> tuple[int, int] | None:
+        ...     if state < 5:
+        ...         return (state * 10, state + 1)
+        ...     return None
+        >>> pc.Iter.unfold(seed=0, generator=counter_generator).into(list)
+        [0, 10, 20, 30, 40]
+        >>> # Example 2: Fibonacci sequence up to 100
+        >>> type FibState = tuple[int, int]
+        >>> def fib_generator(state: FibState) -> tuple[int, FibState] | None:
+        ...     a, b = state
+        ...     if a > 100:
+        ...         return None
+        ...     return (a, (b, a + b))
+        >>> pc.Iter.unfold(seed=(0, 1), generator=fib_generator).into(list)
+        [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
+        >>> # Example 3: Infinite iterator (requires take())
+        >>> pc.Iter.unfold(seed=1, generator=lambda s: (s, s * 2)).take(5).into(list)
+        [1, 2, 4, 8, 16]
+
+        ```
+        """
+        from ._main import Iter
+
+        def _unfold() -> Iterator[V]:
+            current_seed: S = seed
+            while True:
+                result: tuple[V, S] | None = generator(current_seed)
+                if result is None:
+                    break
+                value, next_seed = result
+                yield value
+                current_seed = next_seed
+
+        return Iter(_unfold())