AnyIO

AnyIO is a Python library that provides a single, high-level asynchronous programming API — structured concurrency with task groups, cancellation scopes, sockets, streams, synchronization primitives, and subprocess/thread offloading — that works identically whether the underlying event loop is asyncio or Trio. Rather than choosing between the two ecosystems, library authors can target AnyIO’s API once and let end users run their code on whichever backend they prefer, while application authors get Trio-style structured concurrency (task groups that guarantee child tasks finish or are cancelled before the parent scope exits) even when running on plain asyncio.

AnyIO is widely used as the concurrency layer underneath other popular async libraries (including Starlette/FastAPI’s test client and httpx’s async transport), because it removes the need for those projects to hand-write asyncio/Trio compatibility shims. It also ships a pytest plugin (anyio.pytest_plugin) for testing async code against both backends without duplicating test suites, and provides thread/subprocess/interpreter offloading helpers (to_thread, to_process, to_interpreter) for running blocking or CPU-bound work without blocking the event loop.

What You Get

• Structured concurrency via task groups and cancellation scopes that guarantee child tasks complete or are cancelled before their parent scope exits
• A unified socket/stream API for TCP, UDP, and Unix sockets that behaves identically on asyncio and Trio
• Synchronization primitives (locks, semaphores, events, condition variables) usable from either backend
• Thread, process, and subinterpreter offloading helpers (to_thread, to_process, to_interpreter) for running blocking work off the event loop
• A pytest plugin for running the same async test suite against both asyncio and Trio backends

Common Use Cases

• Library authors writing async I/O code once that needs to run on both asyncio and Trio user applications
• Application developers wanting Trio-style structured concurrency (guaranteed task cleanup) while staying on the asyncio ecosystem
• Frameworks (e.g. web frameworks, HTTP clients) using AnyIO internally as their concurrency primitive layer instead of hand-rolling asyncio/Trio shims
• Offloading blocking or CPU-bound work (file I/O, C extensions) from async code via to_thread/to_process without blocking the event loop
• Testing async libraries against both backends in a single pytest suite via the built-in anyio pytest plugin

Under The Hood

Architecture AnyIO’s public API in src/anyio/_core is backend-agnostic; at runtime it dispatches to one of two backend implementations in src/anyio/_backends — _asyncio.py (which adapts native asyncio primitives, adding structured-concurrency semantics asyncio lacks natively) or _trio.py (a thinner pass-through, since Trio already implements structured concurrency natively). This split lets AnyIO present one API while each backend module handles the real differences in cancellation semantics, task scheduling, and socket implementation between the two runtimes.

Tech Stack Pure Python (3.10+), using setuptools/setuptools_scm for packaging, with idna as its only hard runtime dependency (plus conditional exceptiongroup/typing_extensions backports for older Python versions) and trio as an optional extra for the Trio backend. Ships a py.typed marker for full type-checker support.

Code Quality The tests/ directory (over 15,000 lines including a dedicated streams subdirectory) covers task groups, cancellation, sockets, subprocesses, synchronization, deprecations, and the pytest plugin itself, and both AGENTS.md and CLAUDE.md files in the repo root document contributor/agent conventions directly — an unusually explicit level of process documentation for a library of this size. The project is fully type-annotated and uses blockbuster (a dev dependency) to detect accidental blocking calls inside async code during its own test suite.

API Design The core primitives — anyio.create_task_group(), anyio.CancelScope, anyio.to_thread.run_sync() — closely mirror Trio’s already well-regarded structured-concurrency API, so developers familiar with Trio (or who read AnyIO’s docs) get a consistent mental model regardless of which backend actually executes their code. This deliberate API alignment with Trio, rather than asyncio’s lower-level primitives, is what allows AnyIO to add real cancellation guarantees on top of asyncio without exposing two divergent programming models.