pyochain 0.5.1__py3-none-any.whl → 0.5.2__py3-none-any.whl

pyochain/_iter/_main.py

@@ -1,14 +1,22 @@
 from __future__ import annotations
 
-from collections.abc import Callable, Collection, Generator, Iterable, Iterator
-from typing import TYPE_CHECKING, Any, Concatenate
+import itertools
+from collections.abc import (
+    Callable,
+    Generator,
+    Iterable,
+    Iterator,
+    Sequence,
+)
+from typing import TYPE_CHECKING, Any, Concatenate, overload, override
+
+import cytoolz as cz
 
 from ._aggregations import BaseAgg
 from ._booleans import BaseBool
-from ._constructors import IterConstructors
+from ._dicts import BaseDict
 from ._eager import BaseEager
 from ._filters import BaseFilter
-from ._groups import BaseGroups
 from ._joins import BaseJoins
 from ._lists import BaseList
 from ._maps import BaseMap
@@ -21,8 +29,11 @@ if TYPE_CHECKING:
     from .._dict import Dict
 
 
+class CommonMethods[T](BaseAgg[T], BaseEager[T], BaseDict[T]):
+    pass
+
+
 class Iter[T](
-    BaseAgg[T],
     BaseBool[T],
     BaseFilter[T],
     BaseProcess[T],
@@ -32,18 +43,15 @@ class Iter[T](
     BaseTuples[T],
     BasePartitions[T],
     BaseJoins[T],
-    BaseGroups[T],
-    BaseEager[T],
-    IterConstructors,
+    CommonMethods[T],
 ):
     """
-    A wrapper around Python's built-in iterable types, providing a rich set of functional programming tools.
+    A wrapper around Python's built-in Iterators/Generators types, providing a rich set of functional programming tools.
 
-    It supports lazy evaluation, allowing for efficient processing of large datasets.
+    It's designed around lazy evaluation, allowing for efficient processing of large datasets.
 
-    It is not a collection itself, but a wrapper that provides additional methods for working with iterables.
-
-    It can be constructed from any iterable, including `lists`, `tuples`, `sets`, and `generators`.
+    - To instantiate from a lazy Iterator/Generator, simply pass it to the standard constructor.
+    - To instantiate from an eager Sequence (like a list or set), use the `from_` class method.
     """
 
     __slots__ = ("_data",)
@@ -51,8 +59,160 @@ class Iter[T](
     def __init__(self, data: Iterator[T] | Generator[T, Any, Any]) -> None:
         self._data = data
 
-    def __repr__(self) -> str:
-        return f"{self.__class__.__name__}({self.unwrap().__repr__()})"
+    @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]
+
+        ```
+        """
+
+        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]
+
+        ```
+        """
+
+        return Iter(cz.itertoolz.iterate(func, input))
+
+    @overload
+    @staticmethod
+    def from_[U](data: Iterable[U]) -> Iter[U]: ...
+    @overload
+    @staticmethod
+    def from_[U](data: U, *more_data: U) -> Iter[U]: ...
+    @staticmethod
+    def from_[U](data: Iterable[U] | U, *more_data: U) -> Iter[U]:
+        """
+        Create an iterator from any Iterable, or from unpacked values.
+
+        - 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, or a single value.
+            more_data: Additional values to include if 'data' is not an Iterable.
+        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()
+        []
+        >>> # Creating from unpacked values
+        >>> pc.Iter.from_(1, 2, 3).collect(tuple).unwrap()
+        (1, 2, 3)
+
+        ```
+        """
+        if cz.itertoolz.isiterable(data):
+            return Iter(iter(data))
+        else:
+            d: Iterable[U] = (data, *more_data)  # type: ignore[assignment]
+            return Iter(iter(d))
+
+    @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())
 
     def itr[**P, R, U: Iterable[Any]](
         self: Iter[U],
@@ -86,9 +246,9 @@ class Iter[T](
         """
 
         def _itr(data: Iterable[U]) -> Generator[R, None, None]:
-            return (func(Iter.from_(x), *args, **kwargs) for x in data)
+            return (func(Iter(iter(x)), *args, **kwargs) for x in data)
 
-        return self.apply(_itr)
+        return self._lazy(_itr)
 
     def struct[**P, R, K, V](
         self: Iter[dict[K, V]],
@@ -100,6 +260,7 @@ class Iter[T](
         Apply a function to each element after wrapping it in a Dict.
 
         This is a convenience method for the common pattern of mapping a function over an iterable of dictionaries.
+
         Args:
             func: Function to apply to each wrapped dictionary.
             *args: Positional arguments to pass to the function.
@@ -151,74 +312,158 @@ class Iter[T](
         def _struct(data: Iterable[dict[K, V]]) -> Generator[R, None, None]:
             return (func(Dict(x), *args, **kwargs) for x in data)
 
-        return self.apply(_struct)
+        return self._lazy(_struct)
 
-    def with_keys[K](self, keys: Iterable[K]) -> Dict[K, T]:
+    def apply[**P, R](
+        self,
+        func: Callable[Concatenate[Iterable[T], P], Iterator[R]],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Iter[R]:
         """
-        Create a Dict by zipping the iterable with keys.
+        Apply a function to the underlying Iterator and return a new Iter instance.
+
+        Allow to pass user defined functions that transform the iterable while retaining the Iter wrapper.
 
         Args:
-            keys: Iterable of keys to pair with the values.
+            func: Function to apply to the underlying iterable.
+            *args: Positional arguments to pass to the function.
+            **kwargs: Keyword arguments to pass to the function.
+
         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}
+        >>> 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 .._dict import Dict
+        return self._lazy(func, *args, **kwargs)
 
-        return Dict(dict(zip(keys, self.unwrap())))
-
-    def with_values[V](self, values: Iterable[V]) -> Dict[T, V]:
+    def collect(self, factory: Callable[[Iterable[T]], Sequence[T]] = list) -> Seq[T]:
         """
-        Create a Dict by zipping the iterable with values.
+        Collect the elements into a sequence, using the provided factory.
 
         Args:
-            values: Iterable of values to pair with the keys.
+            factory: A callable that takes an iterable and returns a Sequence. Defaults to list.
+
         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'}
+        >>> pc.Iter.from_(range(5)).collect().unwrap()
+        [0, 1, 2, 3, 4]
 
         ```
         """
-        from .._dict import Dict
+        return self._eager(factory)
+
+    @override
+    def unwrap(self) -> Iterator[T]:
+        """
+        Unwrap and return the underlying Iterator.
 
-        return Dict(dict(zip(self.unwrap(), values)))
+        ```python
+        >>> import pyochain as pc
+        >>> iterator = pc.Iter.from_([1, 2, 3])
+        >>> unwrapped = iterator.unwrap()
+        >>> list(unwrapped)
+        [1, 2, 3]
 
+        ```
+        """
+        return self._data  # type: ignore[return-value]
 
-class Seq[T](BaseAgg[T], BaseEager[T]):
+
+class Seq[T](CommonMethods[T]):
     """
-    pyochain.Seq represent an in memory collection.
+    pyochain.Seq represent an in memory Sequence.
 
     Provides a subset of pyochain.Iter methods with eager evaluation, and is the return type of pyochain.Iter.collect().
     """
 
     __slots__ = ("_data",)
 
-    def __init__(self, data: Collection[T]) -> None:
+    def __init__(self, data: Sequence[T]) -> None:
         self._data = data
 
+    @overload
+    @staticmethod
+    def from_[U](data: Sequence[U]) -> Seq[U]: ...
+    @overload
+    @staticmethod
+    def from_[U](data: U, *more_data: U) -> Seq[U]: ...
+    @staticmethod
+    def from_[U](data: Sequence[U] | U, *more_data: U) -> Seq[U]:
+        """
+        Create a Seq from a Sequence or unpacked values.
+
+        Args:
+            data: Sequence of items or a single item.
+            more_data: Additional item to include if 'data' is not a Sequence.
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Seq.from_([1, 2, 3]).unwrap()
+        [1, 2, 3]
+        >>> pc.Seq.from_(1, 2).unwrap()
+        (1, 2)
+
+        ```
+
+        """
+        if cz.itertoolz.isiterable(data):
+            return Seq(data)
+        else:
+            return Seq((data, *more_data))
+
     def iter(self) -> Iter[T]:
         """
         Get an iterator over the sequence.
         Call this to switch to lazy evaluation.
         """
-        return Iter.from_(self.unwrap())
+        return self._lazy(iter)
+
+    def apply[**P, R](
+        self,
+        func: Callable[Concatenate[Iterable[T], P], Sequence[R]],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Seq[R]:
+        """
+        Apply a function to the underlying Sequence and return a Seq instance.
+
+        Allow to pass user defined functions that transform the Sequence while retaining the Seq wrapper.
+
+        Args:
+            func: Function to apply to the underlying Sequence.
+            *args: Positional arguments to pass to the function.
+            **kwargs: Keyword arguments to pass to the function.
+
+        Example:
+        ```python
+        >>> import pyochain as pc
+        >>> def double(data: Iterable[int]) -> Sequence[int]:
+        ...     return [x * 2 for x in data]
+        >>> pc.Seq([1, 2, 3]).apply(double).into(list)
+        [2, 4, 6]
+
+        ```
+        """
+        return self._eager(func, *args, **kwargs)
+
+    @override
+    def unwrap(self) -> Sequence[T]:
+        """
+        Unwrap and return the underlying Sequence.
+
+        ```python
+        >>> import pyochain as pc
+        >>> pc.Seq([1, 2, 3]).unwrap()
+        [1, 2, 3]
+
+        ```
+        """
+        return self._data  # type: ignore[return-value]

pyochain/_iter/_maps.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
 import itertools
-from collections.abc import Callable, Collection, Generator, Iterable, Iterator, Mapping
+from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence
 from functools import partial
-from typing import TYPE_CHECKING, Any, Concatenate, Self, overload
+from typing import TYPE_CHECKING, Any, Concatenate, overload
 
 import cytoolz as cz
 import more_itertools as mit
@@ -20,29 +20,31 @@ class BaseMap[T](IterWrapper[T]):
         func: Callable[Concatenate[T, P], Any],
         *args: P.args,
         **kwargs: P.kwargs,
-    ) -> Self:
+    ) -> None:
         """
-        Apply a function to each element in the iterable.
+        Consume the Iterator by applying a function to each element in the iterable.
 
         Args:
             func: Function to apply to each element.
             args: Positional arguments for the function.
             kwargs: Keyword arguments for the function.
 
-        Can be used for side effects such as printing or logging.
+        Is a terminal operation, and is useful for functions that have side effects, or when you want to force evaluation of a lazy iterable.
         ```python
         >>> import pyochain as pc
-        >>> pc.Iter.from_([1, 2, 3]).for_each(lambda x: print(x)).collect().unwrap()
+        >>> pc.Iter.from_([1, 2, 3]).for_each(lambda x: print(x))
         1
         2
         3
-        []
 
         ```
         """
-        for v in self.unwrap():
-            func(v, *args, **kwargs)
-        return self
+
+        def _for_each(data: Iterable[T]) -> None:
+            for v in data:
+                func(v, *args, **kwargs)
+
+        return self.into(_for_each)
 
     def map[R](self, func: Callable[[T], R]) -> Iter[R]:
         """
@@ -58,7 +60,7 @@ class BaseMap[T](IterWrapper[T]):
 
         ```
         """
-        return self.apply(partial(map, func))
+        return self._lazy(partial(map, func))
 
     @overload
     def flat_map[U, R](
@@ -94,7 +96,7 @@ class BaseMap[T](IterWrapper[T]):
         def _flat_map(data: Iterable[U]) -> map[R]:
             return map(func, itertools.chain.from_iterable(data))
 
-        return self.apply(_flat_map)
+        return self._lazy(_flat_map)
 
     def map_star[U: Iterable[Any], R](
         self: IterWrapper[U], func: Callable[..., R]
@@ -123,11 +125,12 @@ class BaseMap[T](IterWrapper[T]):
         ['blue-S', 'blue-M', 'red-S', 'red-M']
 
         ```
+
         - Use map_star when the performance matters (it is faster).
         - Use map with unpacking when readability matters (the types can be inferred).
         """
 
-        return self.apply(partial(itertools.starmap, func))
+        return self._lazy(partial(itertools.starmap, func))
 
     def map_if[R](
         self,
@@ -165,7 +168,7 @@ class BaseMap[T](IterWrapper[T]):
 
         ```
         """
-        return self.apply(mit.map_if, predicate, func, func_else=func_else)
+        return self._lazy(mit.map_if, predicate, func, func_else=func_else)
 
     def map_except[R](
         self, func: Callable[[T], R], *exceptions: type[BaseException]
@@ -192,17 +195,17 @@ class BaseMap[T](IterWrapper[T]):
         def _map_except(data: Iterable[T]) -> Iterator[R]:
             return mit.map_except(func, data, *exceptions)
 
-        return self.apply(_map_except)
+        return self._lazy(_map_except)
 
     def repeat(
-        self, n: int, factory: Callable[[Iterable[T]], Collection[T]] = tuple
+        self, n: int, factory: Callable[[Iterable[T]], Sequence[T]] = tuple
     ) -> Iter[Iterable[T]]:
         """
-        Repeat the entire iterable n times (as elements) and return Iter.
+        Repeat the entire iterable n times (as elements).
 
         Args:
             n: Number of repetitions.
-            factory: Factory to create the repeated collection (default: tuple).
+            factory: Factory to create the repeated Sequence (default: tuple).
 
         ```python
         >>> import pyochain as pc
@@ -217,7 +220,7 @@ class BaseMap[T](IterWrapper[T]):
         def _repeat(data: Iterable[T]) -> Iterator[Iterable[T]]:
             return itertools.repeat(factory(data), n)
 
-        return self.apply(_repeat)
+        return self._lazy(_repeat)
 
     @overload
     def repeat_last(self, default: T) -> Iter[T]: ...
@@ -247,7 +250,7 @@ class BaseMap[T](IterWrapper[T]):
 
         ```
         """
-        return self.apply(mit.repeat_last, default)
+        return self._lazy(mit.repeat_last, default)
 
     def ichunked(self, n: int) -> Iter[Iterator[T]]:
         """
@@ -275,7 +278,7 @@ class BaseMap[T](IterWrapper[T]):
 
         ```
         """
-        return self.apply(mit.ichunked, n)
+        return self._lazy(mit.ichunked, n)
 
     @overload
     def flatten[U](
@@ -297,7 +300,7 @@ class BaseMap[T](IterWrapper[T]):
 
         ```
         """
-        return self.apply(itertools.chain.from_iterable)
+        return self._lazy(itertools.chain.from_iterable)
 
     def pluck[U: Mapping[Any, Any]](
         self: IterWrapper[U], *keys: str | int
@@ -333,17 +336,16 @@ class BaseMap[T](IterWrapper[T]):
         """
 
         getter = partial(cz.dicttoolz.get_in, keys)
-        return self.apply(partial(map, getter))
+        return self._lazy(partial(map, getter))
 
     def round[U: float | int](
         self: IterWrapper[U], ndigits: int | None = None
     ) -> Iter[float]:
         """
-        Round each element in the iterable to the given number of decimal places and return Iter.
+        Round each element in the iterable to the given number of decimal places.
 
         Args:
             ndigits: Number of decimal places to round to.
-
         ```python
         >>> import pyochain as pc
         >>> pc.Iter.from_([1.2345, 2.3456, 3.4567]).round(2).into(list)
@@ -355,4 +357,4 @@ class BaseMap[T](IterWrapper[T]):
         def _round(data: Iterable[U]) -> Generator[float | int, None, None]:
             return (round(x, ndigits) for x in data)
 
-        return self.apply(_round)
+        return self._lazy(_round)