~.iterator

CacheIteratorStep

Bases: Protocol[T, U]

Implement a custom iterator pipeline step.

__call__

__call__(item: T) -> tuple[U, bool, bool]

Return (value, skip, stop).

stop = True, skip = True   -> Skip this value, then stop.
stop = True, skip = False  -> Yield this value, then stop.
stop = False, skip = True  -> Skip this value, continue.
stop = False, skip = False -> Yield this value, continue.

CacheIterator

CacheIterator(source: AsyncIterator[T])

Bases: Generic[T]

Asynchronous iterator for cached objects.

Create a new cache iterator from an async iterator.

PARAMETER	DESCRIPTION
source	The source iterator. TYPE: AsyncIterator[T]

Note

The source iterator is shared across transformations created from this iterator. Multiple concurrent iterations are not supported.

add_step

add_step(
    step: CacheIteratorStep[T, U],
) -> CacheIterator[U]

Add a custom-implemented CacheIteratorStep into the iterator's pipeline.

PARAMETER	DESCRIPTION
step	The iterator step to add. TYPE: CacheIteratorStep[T, U]

RETURNS	DESCRIPTION
CacheIterator[U]	A chain-callable async iterator over the results.

all async

all(predicate: Callable[[T], bool]) -> bool

Check if all items in the iterator satisfy a predicate.

PARAMETER	DESCRIPTION
predicate	The predicate to check each item against. TYPE: Callable[[T], bool]

RETURNS	DESCRIPTION
bool	True if all items satisfy the predicate, False otherwise. Returns True if the iterator is empty.

any async

any(predicate: Callable[[T], bool]) -> bool

Check if any item in the iterator satifies a predicate.

PARAMETER	DESCRIPTION
predicate	The predicate to check each item against. TYPE: Callable[[T], bool]

RETURNS	DESCRIPTION
bool	True if any item satisfies the predicate, False otherwise. Returns False if the iterator is empty.

chunk

chunk(size: int) -> CacheIterator[list[T]]

Set the amount of results to be handled in each chunk.

PARAMETER	DESCRIPTION
size	The amount of results. TYPE: int

RETURNS	DESCRIPTION
CacheIterator[list[T]]	A chain-callable async iterator over the results.

collect async

collect() -> list[T]

Collect all items in the iterator into a list.

RETURNS	DESCRIPTION
list[T]	All iterator items.

count async

count() -> int

Get the total amount of items in the iterator.

RETURNS	DESCRIPTION
int	The amount of items.

enumerate

enumerate(start: int = 0) -> CacheIterator[tuple[int, T]]

Enumerate each item, yielding a (index, item) tuple for each result.

PARAMETER	DESCRIPTION
start	The starting index. TYPE: int DEFAULT: 0

RETURNS	DESCRIPTION
CacheIterator[tuple[int, T]]	A chain-callable async iterator over the enumerated results.

filter

filter(
    predicate: Callable[[T], bool],
) -> CacheIterator[T]

Filter through each item in the iterator and check it against a predicate.

PARAMETER	DESCRIPTION
predicate	The predicate method to check against each item. If True, adds the item to the iterator chain. If False, discards it from the iterator chain. TYPE: Callable[[T], bool]

RETURNS	DESCRIPTION
CacheIterator[T]	A chain-callable async iterator over the results.

flat_map

flat_map(
    func: Callable[[T], AsyncIterator[U]],
) -> CacheIterator[U]

Map each item to an async iterator and flatten all results into a single iterator.

PARAMETER	DESCRIPTION
func	A method that takes each item and returns an async iterator of results. TYPE: Callable[[T], AsyncIterator[U]]

RETURNS	DESCRIPTION
CacheIterator[U]	A chain-callable async iterator over the flatten results.

find async

find(predicate: Callable[[T], bool]) -> T | None

Find the first item in the iterator that passes the predicate.

PARAMETER	DESCRIPTION
predicate	The predicate method to check against each item. TYPE: Callable[[T], bool]

RETURNS	DESCRIPTION
T | None	If passed, the first item.

first async

first() -> T | None

Get the first item in the iterator.

RETURNS	DESCRIPTION
T | None	If present, the first item.

last async

last() -> T | None

Get the last item in the iterator.

RETURNS	DESCRIPTION
T | None	If present, the last item.

limit

limit(size: int) -> CacheIterator[T]

Limit the size of the iterator.

PARAMETER	DESCRIPTION
size	The size limit of the iterator. TYPE: int

RETURNS	DESCRIPTION
CacheIterator[T]	A chain-callable async iterator over the results.

map

map(func: Callable[[T], U]) -> CacheIterator[U]

Map each iterator item through a mapping method.

PARAMETER	DESCRIPTION
func	The mapping method. TYPE: Callable[[T], U]

RETURNS	DESCRIPTION
CacheIterator[U]	A chain-callable async iterator over the results.

max async

max(*, key: Callable[[T], Any]) -> T | None

Get the item with the highest key value.

PARAMETER	DESCRIPTION
key	A method used to extract a comparison key from each item. TYPE: Callable[[T], Any]

RETURNS	DESCRIPTION
T | None	If present, the item with the highest key value.

min async

min(*, key: Callable[[T], Any]) -> T | None

Get the item with the lowest key value.

PARAMETER	DESCRIPTION
key	A method used to extract a comparison key from each item. TYPE: Callable[[T], Any]

RETURNS	DESCRIPTION
T | None	If present, the item with the lowest key value.

reduce async

reduce(func: Callable[[U, T], U], initial: U) -> U

Aggregate all iterator items into one value using a reducing method.

PARAMETER	DESCRIPTION
func	The reducing method. TYPE: Callable[[U, T], U]
initial	The initial value. TYPE: U

RETURNS	DESCRIPTION
U	The reduced iterator items.

skip_while

skip_while(
    predicate: Callable[[T], bool],
) -> CacheIterator[T]

Skip items while the predicate returns True, then yield all remaining items.

PARAMETER	DESCRIPTION
predicate	The predicate to check each item against. TYPE: Callable[[T], bool]

RETURNS	DESCRIPTION
CacheIterator[T]	A chain-callable async iterator over the results.

sort async

sort(
    *,
    key: (
        Callable[[T], SupportsRichComparison] | None
    ) = None,
    reverse: bool = False
) -> list[T]

Collect all items (consuming them) and return them sorted.

PARAMETER	DESCRIPTION
key	If provided, a method used to extract a comparison key from each item. TYPE: Callable[[T], SupportsRichComparison] | None DEFAULT: None
reverse	If True, sorts in descending order. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
list[T]	All iterator items, sorted.

take_while

take_while(
    predicate: Callable[[T], bool],
) -> CacheIterator[T]

Yield items while the predicate returns True, then stop.

PARAMETER	DESCRIPTION
predicate	The predicate to check each item against. TYPE: Callable[[T], bool]

RETURNS	DESCRIPTION
CacheIterator[T]	A chain-callable async iterator over the results.

unique

unique(
    *, key: Callable[[T], Hashable] | None = None
) -> CacheIterator[T]

Yield only unique items, discarding duplicates.

PARAMETER	DESCRIPTION
key	If provided, uniqueness is determined by the key value rather than the item itself. TYPE: Callable[[T], Hashable] | None DEFAULT: None

RETURNS	DESCRIPTION
CacheIterator[T]	A chain-callable async iterator over the unique results.

zip

zip(
    other: CacheIterator[U] | AsyncIterator[U],
) -> CacheIterator[tuple[T, U]]

Pair each item with the corresponding item from another async iterator. Stops when either iterator is exhausted.

PARAMETER	DESCRIPTION
other	The async iterator to zip with. TYPE: CacheIterator[U] | AsyncIterator[U]

RETURNS	DESCRIPTION
CacheIterator[tuple[T, U]]	A chain-callable async iterator over the paired results.