The builtins library

The asyncstdlib.builtins library implements Python’s Built-in Functions for (async) functions and (async) iterables.

Iterator reducing

await anext(iterable: async iter T[, default: T]) → T

Retrieve the next item from the async iterator

Raises:

StopAsyncIteration – if iterator is exhausted and default is not set

If default is given, it is returned if the iterator is exhausted. Otherwise, StopAsyncIteration is raised for an exhausted iterator.

Note

This function is not async neutral. The iterator must be an asynchronous iterator, i.e. support the __anext__() method.

await all(iterable: (async) iter T) → bool

Return True if none of the elements of the (async) iterable are false

await any(iterable: (async) iter T) → bool

Return False if none of the elements of the (async) iterable are true

await max(iterable: (async) iter T, *, key: (T) → Any, default: T) → T

Return the largest item from an (async) iterable or from two or more values

Raises:

ValueError – if iterable is empty and default is not set

The key argument specifies a one-argument ordering function like that used for list.sort(). It may be a regular or async callable and defaults to the identity function. The default argument specifies an object to return if the provided iterable is empty. If the iterable is empty and default is not provided, a ValueError is raised.

Note

The two-or-more-arguments variant is not supported, as it does not benefit from being async. Use the builtin max() function instead.

await min(iterable: (async) iter T, *, key: (T) → Any, default: T) → T

Return the smallest item from an (async) iterable or from two or more values

Raises:

ValueError – if iterable is empty and default is not set

The key argument specifies a one-argument ordering function like that used for list.sort(). It may be a regular or async callable and defaults to the identity function. The default argument specifies an object to return if the provided iterable is empty. If the iterable is empty and default is not provided, a ValueError is raised.

Note

The two-or-more-arguments variant is not supported, as it does not benefit from being async. Use the builtin min() function instead.

await sum(iterable: (async) iter T, start: T = 0) → T

Sum of start and all elements in the (async) iterable

Iterator transforming

async for :T in iter(iterable: (async) iter T)

An async iterator object yielding elements from subject

Raises:

TypeError – if subject does not support any iteration protocol

If sentinel is not given, the subject must support the async iteration protocol (the __aiter__() method), the regular iteration protocol (the __iter__() method), or it must support the sequence protocol (the __getitem__() method with integer arguments starting at 0). In either case, an async iterator is returned.

If sentinel is given, subject must be an (async) callable. In this case, iter() provides an async iterator that uses await subject() to produce new values. Once a value equals sentinel, the value is discarded and iteration stops.

See also

Use scoped_iter() to ensure an (async) iterable is eventually closed and only borrowed until then.

async for :T in filter(function: (T) → (await) bool, iterable: (async) iter T)

An async iterator of elements in an (async) iterable filtered by an (async) callable

Barring sync/async translation, filter is equivalent to (element async for args in iterable if await func(element)).

The function may be a regular or async callable. The iterable may be a regular or async iterable.

async for :(T, ...) in zip(*iterables: (async) iter T, strict: bool = True)

Create an async iterator that aggregates elements from each of the (async) iterables

Raises:

ValueError – if the iterables are not equal length and strict is set

The next element of zip is a tuple of the next element of each of its iterables. As soon as any of its iterables is exhausted, zip is exhausted as well. This means that if zip receives n iterables, with the shortest having m elements, it becomes a generator m-times producing an n-tuple.

async for va, vb, vc in zip(a, b, c):
    print(f'a => {va}, b => {vb}, c => {vc}'

If iterables is empty, the zip iterator is empty as well. Multiple iterables may be mixed regular and async iterables.

When called with strict=True, all iterables must be of same length; in this mode zip raises ValueError if any iterables are not exhausted with the others.

Added in version 3.10.0: The strict parameter.

async for :R in map(function: (T, ...) → (await) R, iterable: (async) iter T, ..., /, strict: bool = True)

An async iterator mapping an (async) function to items from (async) iterables

Raises:

ValueError – if the iterables are not equal length and strict is set

At each step, map collects the next item from each iterable and calls function with these items; if function provides an awaitable, it is awaited. The result is the next value of map. Barring sync/async translation, map is equivalent to (await function(*args) async for args in zip(iterables)).

It is important that func receives one item from each iterable at every step. For n iterables, func must take n positional arguments. Similar to zip(), map is exhausted as soon as any of its iterables is exhausted. When called with strict=True, all iterables must be of same length; in this mode map raises ValueError if any iterables are not exhausted with the others.

The function may be a regular or async callable. Multiple iterables may be mixed regular and async iterables.

Added in version 3.14.0: The strict parameter.

async for :(int, T) in enumerate(iterable: (async) iter T, start=0)

An async iterator of running count and element in an (async) iterable

The count begins at start for the first element of iterable, and is incremented by 1 for each further element. The iterable may be a regular or async iterable.

Standard types

await dict(iterable: (async) iter (str, T)=()) → {str: T, ...}

Create a dict from an (async) iterable and keywords

This is equivalent to {key: value async for key, value in iterable} if no keywords are provided.

await list(iterable: (async) iter T = ()) → [T, ...]

Create a list from an (async) iterable

This is equivalent to [element async for element in iterable].

await set(iterable: (async) iter T = ()) → {T, ...}

Create a set from an (async) iterable

This is equivalent to {element async for element in iterable}.

await tuple(iterable: (async) iter T = ()) -> (T, ...)

Create a tuple from an (async) iterable

await sorted(iterable: (async) iter T, *, key: (T) → (await) Any, reverse: bool) → [T, ...]

Sort items from an (async) iterable into a new list

The optional key argument specifies a one-argument (async) callable, which provides a substitute for determining the sort order of each item. The special value and default None represents the identity functions, i.e. compares items directly.

The default sort order is ascending, that is items with a < b imply result.index(a) < result.index(b). Use reverse=True for descending sort order.

Note

The actual sorting is synchronous, so a very large iterable or very slow comparison may block the event loop notably. It is guaranteed to be worst-case O(n log n) runtime.

Added in version 3.9.0.