Metadata-Version: 2.4
Name: backports.asyncio.runner
Version: 1.2.0
Summary: Backport of asyncio.Runner, a context manager that controls event loop life cycle.
Project-URL: Homepage, https://github.com/samypr100/backports.asyncio.runner
Project-URL: Changelog, https://github.com/samypr100/backports.asyncio.runner/blob/main/CHANGELOG.md
Author-email: samypr100 <3933065+samypr100@users.noreply.github.com>
License: PSF-2.0
License-File: LICENSE.md
Keywords: asyncio,asyncio.Runner,backports,backports.asyncio,backports.asyncio.Runner
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Python Software Foundation License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <3.11,>=3.8
Description-Content-Type: text/markdown

# backports.asyncio.runner

[![PyPI version][project-badge]](https://pypi.org/project/backports.asyncio.runner)
[![GitHub Actions][github-actions-badge]](https://github.com/samypr100/backports.asyncio.runner/actions/workflows/main.yml)
[![Hatch][hatch-badge]](https://github.com/pypa/hatch)
[![Ruff][ruff-badge]](https://github.com/astral-sh/ruff)
[![Uv][uv-badge]](https://github.com/astral-sh/uv)
[![Type checked with mypy][mypy-badge]](https://mypy-lang.org)
[![Coverage][coverage-badge]](https://coverage.readthedocs.io)

[project-badge]: https://badge.fury.io/py/backports.asyncio.runner.svg
[github-actions-badge]: https://github.com/samypr100/backports.asyncio.runner/actions/workflows/main.yml/badge.svg
[hatch-badge]: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg
[ruff-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
[uv-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json
[mypy-badge]: https://www.mypy-lang.org/static/mypy_badge.svg
[coverage-badge]: https://gist.githubusercontent.com/samypr100/8682bd2df950670a45095c7c109a176e/raw/coverage.svg

This is a backport of Python 3.11 [asyncio.Runner](https://docs.python.org/3/library/asyncio-runner.html#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:

```python
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](https://github.com/MagicStack/uvloop). An example is below:

```python
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](https://github.com/astral-sh/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](https://github.com/python/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