Registry / web-framework / backports-asyncio-runner

backports-asyncio-runner

library1.2.0pypypi✓ verified 25d ago

Backport of Python 3.11's `asyncio.Runner`, a context manager that simplifies managing the asyncio event loop lifecycle for Python versions 3.8, 3.9, and 3.10. It provides full compatibility with Python 3.11 `asyncio.Runner` features, including contextvars support. Version 1.2.0 is current, with recent releases indicating an active maintenance cadence.

web-framework database auth-security

pip install backports-asyncio-runner

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · BACKPORTS-ASYNCIO-

backports-asyncio-runner

web-frameworkpythonv1.2.0

Install

1.6s avg

Import

162ms

Disk

27MB

Pass rate

6/ 10

Env Coverage6 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 1.55s

py 3.11

✓ —

✓ 1.55s

py 3.12

1/2 runs

py 3.13

1/2 runs

py 3.9

✓ —

✓ 1.75s

27MB installed

● package 27MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Runner

✓ from backports.asyncio.runner import Runner

✗ from asyncio import Runner

The native `asyncio.Runner` is only available in Python 3.11+. For supported older versions (3.8-3.10), use the backport's import path. It's often recommended to use a conditional import based on `sys.version_info`.

This example demonstrates the basic usage of `Runner` as a context manager to execute an asynchronous coroutine. It includes a conditional import to ensure compatibility across Python versions where `Runner` might be native or a backport.

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")) # To use with uvloop (if installed): # import uvloop # with Runner(loop_factory=uvloop.new_event_loop) as runner: # runner.run(echo("UVLoop World"))

Debug

Known issues

breakingThis backport is intended *only* for Python versions 3.8, 3.9, and 3.10. Users of Python 3.11 or above should use the native `asyncio.Runner` from the standard library directly and should *not* install this package.

fix

Ensure installation is guarded by `python_version < '3.11'` markers or simply avoid installing on Python 3.11+.

affects: <3.11 (if incorrectly installed on 3.11+)

gotchaThe backport uses `asyncio.tasks._PyTask` instead of `asyncio.tasks._CTask` internally to support `asyncio.Runner` requirements. This can lead to unexpected behavior or `False` results when checking `isinstance(some_task, asyncio.Task)` or `isinstance(some_future, asyncio.Future)`, as `asyncio.Task` might default to `_CTask` elsewhere.

fix

Be aware of this internal difference; if type checking `asyncio.Task` or `asyncio.Future` is critical, consider testing the specific behavior in your environment or refactoring to avoid strict type checks against the base `asyncio.Task`/`Future` type when tasks are managed by `backports.asyncio.runner`.

affects: 3.8, 3.9, 3.10

gotchaThere is a slight performance degradation when using this backported `asyncio.Runner` implementation compared to the native Python 3.11 or above version. This is due to the lack of a `_CTask` backport.

fix

This is an inherent limitation of the backport. For maximum asyncio performance, upgrading to Python 3.11 or newer is recommended.

affects: 3.8, 3.9, 3.10

gotchaIt's recommended to include a Python version marker (e.g., `python_version < '3.11'`) in your installation commands or `install_requires` to prevent accidental installation of this backport on Python 3.11 or later environments.

fix

Use `pip install 'backports-asyncio-runner; python_version < "3.11"'` or `install_requires=['backports-asyncio-runner; python_version < "3.11"']`.

affects: * (potential incorrect installation on 3.11+)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'backports.asyncio.runner'

The `backports-asyncio-runner` package has not been installed, or the environment where it was installed is not active.

fix

Install the package using pip: `pip install backports-asyncio-runner`.

ModuleNotFoundError: No module named 'asyncio.Runner'

This error occurs when attempting to import `asyncio.Runner` directly on Python versions prior to 3.11, where `Runner` is not part of the standard `asyncio` library.

fix

For Python 3.8, 3.9, or 3.10, install `backports-asyncio-runner` and import `Runner` from the backports package: `from backports.asyncio.runner import Runner`.

isinstance(some_runner_main_task, asyncio.Task) returns False unexpectedly

The `backports.asyncio.runner` implementation uses `asyncio.tasks._PyTask` instead of `asyncio.tasks._CTask` for its internal `asyncio.Task` implementation, which can cause `isinstance` checks against the standard library's `asyncio.Task` to fail if `asyncio.Task` defaults to `_CTask` in your environment.

fix

To safely check the type, consider checking `isinstance(some_runner_main_task, (asyncio.Task, backports.asyncio.runner.Task))` or avoid direct type checking where possible, relying on duck typing or the expected behavior of tasks within the `Runner` context.

Upgrade

Version history

1.2.0latest on PyPI · released Jul 2, 2025

Audit

Dependencies

Python 3.8, 3.9, or 3.10requiredThis library is a backport specifically for these Python versions; it is not needed and should not be used on Python 3.11 or newer.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/samypr100/backports.asyncio.runner ↗

packagehttps://pypi.org/project/backports-asyncio-runner/ ↗

changeloghttps://github.com/samypr100/backports.asyncio.runner/blob/main/CHANGELOG.md ↗