Trio — Structured Concurrency for Python

Introduction

Trio rethinks Python's async concurrency around the principle of structured concurrency: every concurrent task belongs to a nursery that manages its lifetime. This eliminates orphaned tasks, guarantees cleanup, and makes error handling predictable in ways that raw asyncio cannot.

What Trio Does

• Runs concurrent async tasks within nurseries that enforce lifetime boundaries
• Guarantees that exceptions propagate cleanly and all child tasks finish before the parent continues
• Provides cancellation scopes with deadlines and cancel tokens
• Offers high-level networking, file I/O, and synchronization primitives
• Eliminates common async bugs like fire-and-forget tasks and swallowed exceptions

Architecture Overview

Trio uses a single-threaded event loop with cooperative scheduling. The nursery abstraction forms a task tree where each nursery awaits all its child tasks before returning. Cancellation flows downward through the tree via cancel scopes. The I/O layer uses platform-native APIs (epoll, kqueue, IOCP) through a thin abstraction.

Self-Hosting & Configuration

• Install via pip; supports Python 3.8+
• No configuration files; use trio.run() as the entry point
• Add trio-compatible libraries (httpx, asks, trio-websocket) for network clients
• Use trio.testing module for deterministic async test helpers
• Combine with Hypercorn or Uvicorn (via anyio) for web server deployment

Key Features

• Nurseries guarantee no orphaned tasks and proper cleanup on failure
• Cancel scopes with deadlines provide structured timeouts
• Checkpoints are explicit, making it clear where context switches occur
• Rich debugging support with task tree introspection
• Designed for correctness first, then performance

Comparison with Similar Tools

• asyncio — stdlib but allows fire-and-forget tasks and has complex cancellation; Trio enforces structure
• anyio — compatibility layer that runs on both asyncio and Trio backends
• Twisted — callback-based (with deferred); Trio uses native async/await
• Curio — similar structured approach but less actively maintained; Trio has a larger ecosystem

FAQ

Q: Can I use Trio with existing asyncio libraries? A: Use the trio-asyncio bridge or choose libraries built on anyio which supports both backends natively.

Q: What is structured concurrency? A: A paradigm where concurrent tasks are scoped to a block (nursery). When the block exits, all tasks inside it have completed or been cancelled. No task can outlive its parent scope.

Q: Is Trio production-ready? A: Yes. Trio is used in production systems and has a stable API. Libraries like httpx and Starlette support it via anyio.

Q: How does Trio handle timeouts? A: Wrap code in with trio.move_on_after(seconds): or with trio.fail_after(seconds): to apply cancel-scope deadlines that propagate to all child tasks.

Sources

• https://github.com/python-trio/trio
• https://trio.readthedocs.io