Registry / http-networking / aiotools

aiotools

JSON →
library2.2.4pypypi✓ verified 22d ago

aiotools is a collection of idiomatic utilities designed to reduce boilerplate code when working with `asyncio`. It provides robust solutions for safe cancellation, structured concurrency through `TaskScope`, asynchronous context managers, multi-process server daemons, and other high-level coroutine utilities. The library is actively maintained and currently at version 2.2.3, with a release cadence that includes regular bug fixes and feature enhancements, targeting Python 3.11 and newer.

pip install aiotools
INSTALL
IMPORT
SIG · AIOTOOLS
A
aiotools
http-networkingpythonv2.2.4
Install
1.6s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.9.2 · 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
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage

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

TaskScope
from aiotools import TaskScope
from aiotools import TaskScope

This quickstart demonstrates `TaskScope`, a core feature for structured concurrency. It launches multiple worker coroutines within a `TaskScope`. The `async with TaskScope()` block ensures that all child tasks created within it are either completed or cancelled before the block is exited, providing safe lifecycle management. This example also shows how to await individual tasks and retrieve their results.

import asyncio from aiotools import TaskScope async def worker(name, delay): try: print(f"Worker {name}: Starting...") await asyncio.sleep(delay) print(f"Worker {name}: Finished after {delay}s.") return f"Result from {name}" except asyncio.CancelledError: print(f"Worker {name}: Was cancelled!") raise except Exception as e: print(f"Worker {name}: Encountered error: {e}") raise async def main(): print("Main: Starting TaskScope example") async with TaskScope() as scope: task1 = scope.create_task(worker("Alpha", 2)) task2 = scope.create_task(worker("Beta", 1)) task3 = scope.create_task(worker("Gamma", 3)) # You can await individual tasks within the scope print(f"Main: Awaiting Task Beta...") result2 = await task2 print(f"Main: Task Beta finished with: {result2}") print("Main: All tasks in TaskScope are complete or cancelled.") # After exiting the TaskScope, all tasks are guaranteed to be done. # Results and exceptions from other tasks can be retrieved if needed. print(f"Main: Task Alpha result: {task1.result()}") print(f"Main: Task Gamma result: {task3.result()}") if __name__ == "__main__": asyncio.run(main())
Debug
Known issues
breakingThe `TaskGroup` class has been deprecated since `aiotools` v2.0 in favor of `TaskScope`. While `TaskGroup` still exists, `TaskScope` is the recommended high-level API for structured concurrency and provides behavior consistent with `asyncio.TaskGroup` introduced in Python 3.11.
fix
Migrate usage from `aiotools.TaskGroup` to `aiotools.TaskScope` for new and existing code. `TaskScope` handles sibling task failures gracefully without cancelling others.
affects: >=2.0.0
deprecatedThe `aiotools.func.apartial` utility was deprecated in `aiotools` v2.0. Python's built-in `functools.partial()` now works seamlessly with asynchronous functions as of Python 3.8 and should be used instead.
fix
Replace `aiotools.func.apartial` with `functools.partial`.
affects: >=2.0.0
gotchaThe `aiotools.timer.VirtualClock` feature, used for deterministic testing of `asyncio.sleep()` calls, relies on patching event loop internals and is only functional on UNIX-like operating systems. It will not work on Windows.
fix
Avoid using `VirtualClock` in cross-platform test suites or provide platform-specific test runners. Consider alternative time-mocking libraries for Windows compatibility if `VirtualClock`'s specific features are not strictly required.
affects: all
gotchaUnderstanding the difference in error handling between `TaskScope` and `asyncio.TaskGroup` (which `aiotools.TaskGroup` wrapped prior to Python 3.11, and `TaskScope` now extends). `TaskScope` is designed for server-oriented tasks where the failure of one child task does NOT automatically cancel all other sibling tasks, allowing for more resilient services. `asyncio.TaskGroup` (and older `aiotools.TaskGroup` behavior) will cancel all siblings if one task raises an unhandled exception.
fix
Design your concurrency patterns carefully. Use `TaskScope` when you need independent tasks within a group that can fail without affecting siblings (e.g., background workers in a server). Use `asyncio.TaskGroup` (or `TaskScope` if its behavior matches) when tasks are interdependent and a single failure should halt the entire group.
affects: all
gotchaWhen manually cancelling `asyncio` tasks, ensure to use `aiotools.cancel.cancel_and_wait()` for consistent behavior. Without it, managing `CancelledError` propagation (re-raising vs. absorbing) can be tricky and lead to inconsistencies across your codebase, especially prior to Python 3.11's structured concurrency improvements.
fix
Always use `await aiotools.cancel.cancel_and_wait(task)` when you need to cancel an `asyncio` task, instead of `task.cancel(); await task` directly. This ensures predictable handling of `CancelledError`.
affects: <3.11
Upgrade
Version history
2.2.4latest on PyPI · released Jul 21, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.11 or newer for core features and API compatibility.
Agent activity
46 hits · last 30 days
node
40
OpenAI (training)
1
Resources
aiotools — pip install aiotools · libregistry