The missing async toolbox

Documentation Status Available on PyPI Available on Conda-Forge License Development Chat

The asyncstdlib library re-implements functions and classes of the Python standard library to make them compatible with async callables, iterables and context managers. It is fully agnostic to async event loops and seamlessly works with asyncio, third-party libraries such as trio, as well as any custom async event loop.

Standard Library Modules

All re-implementations are located in submodules of asyncstdlib with the same name as those of the Python standard library.

asyncstdlib.builtins

Replicates any Built-in Functions that benefit from being asynchronous, such as zip(), sum(), or list().

asyncstdlib.functools

Replicates any functools that benefit from being asynchronous, which is just reduce(), cached_property(), and lru_cache().

asyncstdlib.contextlib

Replicates any contextlib tools that benefit from being asynchronous, such as contextmanager(), or closing().

asyncstdlib.itertools

Replicates any itertools that benefit from being asynchronous, such as cycle(), chain(), or accumulate().

asyncstdlib.heapq

Replicates any heapq tools that benefit from being asynchronous, which is just merge(), nlargest(), and nsmallest().

For simplicity, the asyncstdlib namespace also exposes all individual functions and classes directly. For example, asyncstdlib.builtins.enumerate is also available as asyncstdlib.enumerate.

The Async Library Module

The core toolset used by asyncstdlib itself is available as a separate submodule.

asyncstdlib.asynctools

Collects any asyncstdlib tools useful for building well-behaved async helpers and programs.

Async Neutral Arguments

Many objects of asyncstdlib are async neutral – they accept both regular and async arguments. Type annotations use parentheses to denote this; for example, “(async) iter T” in the signature zip(*iterables: (async) iter T) means that asyncstdlib’s zip() can handle both synchronous and asynchronous iterables.

Whether a callable is regular or async is determined by inspecting its return type at runtime. This supports async-producing factories, such as an async def function wrapped in functools.partial. However, this also means that the result must consistently be either regular or async.

Note that only arguments to asyncstdlib may be async neutral. All callables of asyncstdlib consistently provide awaitables, asynchronous iterators, and asynchronous context managers.

Async Iterator Cleanup

Cleanup of async iterables is special in that aclose() may require an active event loop. Thus, all utilities of asyncstdlib that work on async iterators will eagerly aclose() them. Use borrow() to prevent automatic cleanup, and scoped_iter() to guarantee cleanup in custom code.

See the guide on Iterator Scoping for details and usage examples.

Indices and tables