The missing async
toolbox¶
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()
, orlist()
.asyncstdlib.functools
Replicates any
functools
that benefit from being asynchronous, which is justreduce()
,cached_property()
, andlru_cache()
.asyncstdlib.contextlib
Replicates any
contextlib
tools that benefit from being asynchronous, such ascontextmanager()
, orclosing()
.asyncstdlib.itertools
Replicates any
itertools
that benefit from being asynchronous, such ascycle()
,chain()
, oraccumulate()
.asyncstdlib.heapq
Replicates any
heapq
tools that benefit from being asynchronous, which is justmerge()
,nlargest()
, andnsmallest()
.
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-behavedasync
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.