Metadata-Version: 2.4
Name: py-asyncutils
Version: 1.0.0
Summary: A library containing versatile tools to well complement the asyncio framework.
Keywords: asynchronous,asyncio,convenient,fast,feature-rich,helpers,io,library,light,utilities
Author: Jonathan Dung
Author-email: Jonathan Dung <jonathandung@yahoo.com>
License-Expression: MIT
License-File: AUTHORS.md
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Unix Shell
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: GraalPy
Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pytest
Classifier: Framework :: Sphinx
Classifier: Natural Language :: English
Classifier: Typing :: Typed
Requires-Dist: py-asyncutils[dev,executors,pconf,themes,ptw]==1.0.0 ; extra == 'all'
Requires-Dist: pre-commit>=4.6.0 ; extra == 'dev'
Requires-Dist: py-asyncutils[themes,test]==1.0.0 ; extra == 'dev'
Requires-Dist: sphinx>=9.1.0 ; extra == 'docs'
Requires-Dist: sphinx-autoapi>=3.8.0 ; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5.2 ; extra == 'docs'
Requires-Dist: sphinx-notfound-page>=1.1.0 ; extra == 'docs'
Requires-Dist: sphinx-lint>=1.0.2 ; extra == 'docs'
Requires-Dist: sphinxext-opengraph[social-cards]>=0.13.0 ; extra == 'docs'
Requires-Dist: myst-parser>=5.1.0 ; extra == 'docs'
Requires-Dist: deadpool-executor>=2026.4.1 ; extra == 'executors'
Requires-Dist: executorlib>=1.10.0 ; extra == 'executors'
Requires-Dist: ipyparallel>=9.2.0 ; extra == 'executors'
Requires-Dist: loky>=3.5.6 ; extra == 'executors'
Requires-Dist: pebble>=5.2.0 ; extra == 'executors'
Requires-Dist: pyjson5>=2.0.1 ; extra == 'json5'
Requires-Dist: hjson>=3.1.0 ; extra == 'pconf'
Requires-Dist: json-with-comments>=1.2.10 ; extra == 'pconf'
Requires-Dist: pyyaml>=6.0.3 ; extra == 'pconf'
Requires-Dist: xmltodict>=1.0.4 ; extra == 'pconf'
Requires-Dist: py-asyncutils[json5]==1.0.0 ; extra == 'pconf'
Requires-Dist: pytest-watch>=4.2.0 ; extra == 'ptw'
Requires-Dist: pytest>=9.1.0 ; extra == 'test'
Requires-Dist: pytest-asyncio>=1.4.0 ; extra == 'test'
Requires-Dist: pytest-asyncio-cooperative>=0.40.0 ; extra == 'test'
Requires-Dist: pytest-cov>=7.1.0 ; extra == 'test'
Requires-Dist: pytest-local-badge>=1.1.1 ; extra == 'test'
Requires-Dist: pytest-sugar>=1.1.1 ; extra == 'test'
Requires-Dist: py-asyncutils[json5]==1.0.0 ; extra == 'test'
Requires-Dist: furo>=2025.12.19 ; extra == 'themes'
Requires-Dist: sphinx-book-theme>=1.2.0 ; extra == 'themes'
Requires-Dist: py-asyncutils[docs]==1.0.0 ; extra == 'themes'
Maintainer: Jonathan Dung
Maintainer-email: Jonathan Dung <jonathandung@yahoo.com>
Requires-Python: >=3.12
Project-URL: Homepage, https://jonathandung.github.io/asyncutils
Project-URL: Documentation, https://asyncutils.readthedocs.io/en/stable/index.html
Project-URL: Repository, https://github.com/jonathandung/asyncutils.git
Project-URL: Issues, https://github.com/jonathandung/asyncutils/issues
Project-URL: Changelog, https://asyncutils.readthedocs.io/en/stable/changelog.html
Project-URL: Download, https://pypi.org/project/py-asyncutils/#files
Project-URL: Release Notes, https://github.com/jonathandung/asyncutils/releases/tag/1.0.0
Provides-Extra: all
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: executors
Provides-Extra: json5
Provides-Extra: pconf
Provides-Extra: ptw
Provides-Extra: test
Provides-Extra: themes
Description-Content-Type: text/markdown

# asyncutils

[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/py-asyncutils)](https://www.python.org/downloads)
[![PyPI version](https://badge.fury.io/py/py-asyncutils.svg)](https://pypi.org/p/py-asyncutils)
[![Coverage](https://raw.githubusercontent.com/jonathandung/asyncutils/main/badges/coverage.svg)](https://github.com/jonathandung/asyncutils/tree/main/tests)
[![Build](https://github.com/jonathandung/asyncutils/actions/workflows/push.yaml/badge.svg)](https://github.com/jonathandung/asyncutils/actions/workflows/python-package.yaml)
[![CodeQL](https://github.com/jonathandung/asyncutils/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/jonathandung/asyncutils/actions/workflows/github-code-scanning/codeql)
[![Publish](https://github.com/jonathandung/asyncutils/actions/workflows/release.yaml/badge.svg)](https://github.com/jonathandung/asyncutils/actions/workflows/python-publish.yaml)
[![GitHub Pages](https://github.com/jonathandung/asyncutils/actions/workflows/deploy.yaml/badge.svg)](https://jonathandung.github.io/asyncutils)
[![Dependabot](https://github.com/jonathandung/asyncutils/actions/workflows/dependabot/update-graph/badge.svg)](https://github.com/jonathandung/asyncutils/actions/workflows)
[![pre-commit.ci](https://results.pre-commit.ci/badge/github/jonathandung/asyncutils/main.svg)](https://results.pre-commit.ci/latest/github/jonathandung/asyncutils/main)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13018/badge)](https://www.bestpractices.dev/projects/13018)
[![Read the Docs: stable build](https://img.shields.io/readthedocs/asyncutils/stable?logo=readthedocs&label=docs%20(stable))](https://asyncutils.readthedocs.io/en/stable)
[![Read the Docs: latest build](https://img.shields.io/readthedocs/asyncutils/latest?logo=readthedocs)](https://asyncutils.readthedocs.io/en)
[![Conda version](https://anaconda.org/conda-forge/py-asyncutils/badges/version.svg)](https://anaconda.org/channels/conda-forge/packages/py-asyncutils/overview)
[![conda-forge feedstock](https://img.shields.io/conda/v/conda-forge/py-asyncutils?logo=condaforge)](https://github.com/conda-forge/py-asyncutils-feedstock)
[![Contributor Covenant](https://img.shields.io/badge/Contributor_Covenant-v3.0-ff69b4.svg?logo=contributor-covenant&logoColor=purple)](https://asyncutils.readthedocs.io/en/stable/conduct.html)

A Python library abstracting all the common patterns I can think of that somehow always pop up in async code.

Includes a wide range of submodules tailored for specific usages, though concrete low-level implementations are lacking.

Takes pride in:

- being as fast as can be in terms of import time
- providing detailed type checking via stub files included in the distribution
- having a well-equipped command line interface taking many flags and options

## Setup

Make sure you have CPython 3.12 or above; even a pre-release of 3.15 will do. GraalPy 25.0 or above is also acceptable. You should have at least one
Python package manager you are comfortable with. CPython free-threaded and debug builds are also supported. I have plans to support PyPy, but they are
currently lagging behind the releases of the reference implementation and a 3.11 backport would be required, which is not going to happen.

The support for GraalPy is also experimental and I don't think its particular performance benefits would apply to this library, provided that part of
`asyncio` is written in C, and GraalPy's `asyncio` doesn't support Windows yet.

Discounting the installation, no extra setup is needed. See the [installation guide](https://asyncutils.readthedocs.io/en/stable/installation.html)
for more.

## Usage

This package is very resourceful, containing everything from higher-order error handling functions to network protocols. See the
[usage guide](https://asyncutils.readthedocs.io/en/stable/examples.html) for some basic examples.

## Version

This is asyncutils v1.0.0. For your reference, here are [all version tags up to now](https://github.com/jonathandung/asyncutils/tags).

## Configuration

Besides using command line arguments to change console settings, the behaviour of this module as a library can be customized as well. See the
[configuration guide](https://asyncutils.readthedocs.io/en/stable/config.html).

## Remarks

It is strongly recommended that you read the [asyncio docs](https://docs.python.org/3/library/asyncio.html) thoroughly if using event loop and async
generator related features, since their behaviours are central points of confusion and have troubled me greatly in the development of this library.

## Resources

Here are some resources if you're new to the world of async. They were of great assistance when I was learning async (I still am):

- [asyncio how-to](https://docs.python.org/3/howto/a-conceptual-overview-of-asyncio.html)
- [Basic walkthrough](https://realpython.com/async-io-python)
- [Basic video guide](https://www.youtube.com/watch?v=t5Bo1Je9EmE)
- [asyncio, threading, multiprocessing](https://www.youtube.com/watch?v=0vFgKr5bjWI)
- [Event loop](https://www.youtube.com/watch?v=RIVcqT2OGPA)
- [In-depth tutorial](https://www.youtube.com/watch?v=oAkLSJNr5zY)

## Contributing

If you have suggestions for how asyncutils could be improved, or want to report a bug, do open an issue! All contributions are welcome.
For more, check out the [contributing guide](https://asyncutils.readthedocs.io/en/stable/contributing.html).

## License

[MIT](https://github.com/jonathandung/asyncutils/blob/main/LICENSE) © 2026 Jonathan Dung

## Badges

| GitHub | Repo | Package | Uses | Status | Tests |
| --- | --- | --- | --- | --- | --- |
| ![GitHub release](https://img.shields.io/github/v/release/jonathandung/asyncutils) | ![Project stars](https://img.shields.io/github/stars/jonathandung/asyncutils?style=social) | ![PyPI - Implementation](https://img.shields.io/pypi/implementation/py-asyncutils) | ![Build backend](https://img.shields.io/badge/build_backend-uv-261230?logo=uv) | ![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-brightgreen.svg) | ![Tests](https://raw.githubusercontent.com/jonathandung/asyncutils/main/badges/tests.svg) |
| ![GitHub release date](https://img.shields.io/github/release-date-pre/jonathandung/asyncutils) | ![GitHub forks](https://img.shields.io/github/forks/jonathandung/asyncutils?style=social) | ![Noarch](https://anaconda.org/conda-forge/py-asyncutils/badges/platforms.svg) | ![ruff](https://img.shields.io/badge/linter-ruff-261230?logo=ruff) | ![Issues Welcome](https://img.shields.io/badge/Issues-Welcome-brightgreen) | ![Warnings](https://raw.githubusercontent.com/jonathandung/asyncutils/main/badges/warnings.svg) |
| ![Commits since last release](https://img.shields.io/github/commits-since/jonathandung/asyncutils/latest) | ![GitHub watchers](https://img.shields.io/github/watchers/jonathandung/asyncutils?style=social) | ![PyPI - Downloads](https://img.shields.io/pypi/dm/py-asyncutils) | ![ty](https://img.shields.io/badge/type_checker-ty-261230?logo=ty) | ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg) | ![Expected failures](https://raw.githubusercontent.com/jonathandung/asyncutils/main/badges/xfailed.svg) |
| ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/jonathandung/asyncutils) | ![GitHub](https://img.shields.io/github/followers/jonathandung?style=social) | ![PyPI - Format](https://img.shields.io/pypi/format/py-asyncutils) | ![SemVer](https://img.shields.io/badge/semver-2.0.0-green?logo=semver) | | ![Duration](https://raw.githubusercontent.com/jonathandung/asyncutils/main/badges/duration.svg) |
| ![GitHub issues](https://img.shields.io/github/issues/jonathandung/asyncutils) | ![GitHub Downloads](https://img.shields.io/github/downloads/jonathandung/asyncutils/total) | ![PyPI - License](https://img.shields.io/pypi/l/py-asyncutils?logo=opensourceinitiative) | ![Sphinx](https://img.shields.io/badge/docs-sphinx-265094?logo=sphinx) | [![Blazingly fast](https://www.blazingly.fast/api/badge.svg?repo=jonathandung%2Fasyncutils)](https://www.blazingly.fast) | ![Skipped](https://raw.githubusercontent.com/jonathandung/asyncutils/main/badges/skipped.svg) |
| ![GitHub pull requests](https://img.shields.io/github/issues-pr/jonathandung/asyncutils) | ![Repo creation](https://img.shields.io/github/created-at/jonathandung/asyncutils) | ![Language count](https://img.shields.io/github/languages/count/jonathandung/asyncutils) | ![Sphinx-lint](https://img.shields.io/badge/sphinx--lint-darkblue?logo=sphinx) | ![Free-threaded support](https://img.shields.io/badge/free_threading-supported-blue) | ![Last test run](https://raw.githubusercontent.com/jonathandung/asyncutils/main/badges/last-run.svg) |
| ![GitHub contributors](https://img.shields.io/github/contributors/jonathandung/asyncutils) | ![GitHub repo size](https://img.shields.io/github/repo-size/jonathandung/asyncutils) | ![Top language](https://img.shields.io/github/languages/top/jonathandung/asyncutils) | ![detect-secrets](https://img.shields.io/badge/detect--secrets-checked-blue?logo=yelp) | | |
| ![GitHub last commit](https://img.shields.io/github/last-commit/jonathandung/asyncutils) | ![Code size](https://img.shields.io/github/languages/code-size/jonathandung/asyncutils) | | ![Pytest](https://img.shields.io/badge/tests-Pytest-yellow?logo=pytest) | | |
