This is a backport of Python 3.11 asyncio.Runner, a context manager that simplifies multiple async function calls in the same context.
This backports provides full compatibility with Python 3.11 asyncio.Runner
features, including contextvars.Context
support.
As such, the Python 3.11 test suite for asyncio.Runner
is used as-is to test its functionality.
This backport is meant to work with Python 3.8, 3.9, and 3.10 only. Users of Python 3.11 or above should not use this package directly.
To install, you can use python -m pip install backports.asyncio.runner
or your favorite python package manager.
You might need to include a marker (e.g. python_version < '3.11'
) to prevent installation on Python 3.11 or above.
An example of the recommended way to use this context manager is in the below code snippet:
import sys
if sys.version_info < (3, 11):
from backports.asyncio.runner import Runner
else:
from asyncio import Runner
async def echo(msg: str) -> None:
print(f"Hello {msg}")
with Runner() as runner:
runner.run(echo("World"))
# Hello World
This backport is also compatible with uvloop. An example is below:
import sys
import uvloop
if sys.version_info < (3, 11):
from backports.asyncio.runner import Runner
else:
from asyncio import Runner
async def echo(msg: str) -> None:
print(f"Hello {msg}")
with Runner(loop_factory=uvloop.new_event_loop) as runner:
runner.run(echo("World"))
# Hello World
Feel free to open a PR if there's changes you'd like to make as long as the changes maintain full reference implementation
with Python 3.11's implementation of asyncio.Runner
. More documentation and additional tests are always welcome as CPython's
test don't seem to provide 100% coverage at a glance or more likely I may have missed including some tests.
- ruff is used to format the code via
ruff format
.- To quickly run ruff, make sure
pipx
is installed an runpipx run ruff==0.6.1 format src tests
- To quickly run ruff, make sure
- mypy is used to check types in the sources (while attempting to stay true to reference implementation).
- To quickly run mypy, make sure
pipx
is installed an runpipx run mypy==1.11.1 src
- To quickly run mypy, make sure
- To run tests use
python -m unittest discover -s tests
. - To gather coverage:
- Install coverage:
python -m pip install "coverage[toml]==7.6.1"
- Run it:
coverage run -m unittest discover -s tests
- Install coverage:
Relevant reference implementation sources:
- https://github.com/python/cpython/blob/3.11/Lib/asyncio/runners.py
- https://github.com/python/cpython/blob/3.11/Lib/asyncio/tasks.py
- https://github.com/python/cpython/blob/3.11/Lib/asyncio/base_events.py
- https://github.com/python/cpython/blob/3.11/Modules/_asynciomodule.c
- https://github.com/python/cpython/blob/3.11/Lib/test/test_asyncio/test_runners.py
- https://github.com/python/cpython/blob/3.8/Lib/test/test_asyncio/test_tasks.py
- https://github.com/python/cpython/blob/3.9/Lib/test/test_asyncio/test_tasks.py
- https://github.com/python/cpython/blob/3.10/Lib/test/test_asyncio/test_tasks.py
This implementation uses asyncio.tasks._PyTask
instead of asyncio.tasks._CTask
as it adds additional functionality to
asyncio.Task
in order to support asyncio.Runner
requirements. Hence, the asyncio.Task
implementation Runner
will
use also comes from this package. As such, problems can arise when checking isinstance(some_runner_main_task, asyncio.Task)
since asyncio.Task
can point to _CTask
by default instead of _PyTask
. You may encounter the same issue when comparing
it to asyncio.Future
.
To guarantee full asyncio.Task
functionality, upstream tests for asyncio.Task
for 3.8, 3.9, and 3.10 are also part of the
testing suite of this package to make sure all changes to asyncio.Task
used by the Runner
are fully compatible with
asyncio.Task
. Important Note: asyncio.Task
is only patched on the Runner
, not globally, hence there should be
no side effects to external code when using this module.
Currently, a backport of _CTask
is not provided on this package and not in scope at this time. This means that there's a slight
performance degradation when using this asyncio.Runner
implementation over the one in Python 3.11 or above.