backports.asyncio.runner

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

uvloop

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

Contributing

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 run ruff, make sure uv is installed and run uv run ruff format src tests
  • To run ruff on applicable python versions, run uv run nox -rs fmt
• mypy is used to check types in the sources (while attempting to stay true to reference implementation).
  • To run mypy, make sure uv is installed and run uv run mypy src
  • To run mypy on applicable python versions, run uv run nox -rs ty
• To run tests use uv run python -m unittest discover -s tests
  • For applicable python versions uv run nox -rs tests
• To gather coverage use uv run coverage run -m unittest discover -s tests
  • For applicable python versions uv run nox -rs tests -- --cov

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

Caveats

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.

1.2.0

• Backport bug fix for https://github.com/python/cpython/issues/112559
• Declare patch and patch.patch_object as internal.
• Improved runner.py typedefs.

1.1.0

• Add basic noxfile with uv backend.
• Simplified patching implementation.
• Test dependency updates.

1.0.2

• Add uvloop example to README.md
• Improved tests coverage.
• Improved modified code documentation.

1.0.1

• requires-python metadata is now properly set to ">=3.8,<3.11"

1.0.0

• Initial Reference Implementation