Problem Addressed

Trio

Overview

Trio is a Python library for async concurrency and I/O that introduced the "structured concurrency" paradigm to the Python ecosystem. Unlike asyncio, Trio guarantees that tasks run to completion within explicit scopes called "nurseries," making concurrent code easier to reason about and debug. The library prioritizes usability and correctness over raw performance, with a design philosophy that makes it hard to write incorrect concurrent code.

Problem Addressed

Key Statistics

Key Features

Structured Concurrency

• Nurseries: Explicit scope for spawning concurrent tasks
• Task completion guarantee: All tasks spawned in a nursery complete before nursery exits
• Exception propagation: Exceptions from child tasks propagate to parent naturally
• No orphan tasks: Impossible to spawn tasks that outlive their caller
• Composability: Nurseries can nest, preserving structured concurrency at all levels

Cancel Scopes

• Unified cancellation: Single mechanism for timeouts and cancellation
• Scope-based: Cancellation applies to a defined scope, not arbitrary tasks
• Composable timeouts: fail_after() and move_on_after() context managers
• Cancellation reasons: v0.31.0+ supports attaching reason strings to cancellations
• Shielding: Protect critical sections from cancellation when needed

Checkpoint System

• Static guarantees: Each function is always or never a checkpoint (no runtime variation)
• Unified points: Cancel points and schedule points are always the same
• Async sandwich: await marks all potential checkpoints visibly in code
• Synchronous safety: Regular (sync) functions never contain checkpoints

Core Primitives

• Tasks: Primary unit of concurrency (no threads, no callbacks)
• Events: Coordination primitive for signaling between tasks
• Channels: Memory channels for inter-task communication (send/receive)
• Locks and Semaphores: Standard synchronization primitives
• Capacity Limiters: Control concurrent access to limited resources

I/O Support

• Sockets: Full TCP/UDP networking with happy eyeballs
• SSL/TLS: Native TLS support with proper async integration
• DTLS: Datagram TLS support (v0.31.0+)
• Subprocesses: Async subprocess management
• File I/O: Via thread pool for non-blocking file operations
• Signals: Cross-platform signal handling

Platform Support

• Operating Systems: Linux, macOS, Windows, FreeBSD
• Python Implementations: CPython 3.10+, PyPy3
• Pure Python: No C extensions required (except CFFI on Windows)

Technical Architecture

Design Principles

1. Usability over speed: Optimize for correctness and ease of use
2. Explicit concurrency: All task spawning is visible in code
3. Causal APIs: No callbacks or implicit concurrency
4. Exception-based errors: Standard Python error handling patterns
5. Context manager cleanup: try/finally and with work correctly

Checkpoint Rules

1. Synchronous functions: NEVER checkpoints
2. Trio async functions (no exception): ALWAYS checkpoints
3. Trio async functions (exception): MAY be checkpoints
4. Third-party async functions: UNKNOWN (treat as potential checkpoints)

Nursery Lifecycle

async with trio.open_nursery() as nursery:
    nursery.start_soon(task1)    # Spawn task 1
    nursery.start_soon(task2)    # Spawn task 2
    # ... more spawning ...
# <-- All tasks MUST complete before reaching here
# <-- Exceptions from any task propagate here

Cancel Scope Nesting

with trio.move_on_after(10):           # Outer: 10 second timeout
    with trio.fail_after(5):           # Inner: 5 second timeout
        await long_operation()         # Subject to 5-second limit
    await another_operation()          # Subject to 10-second limit

Dependencies

Installation and Usage

Installation

# Using pip
pip install trio

# Using uv (recommended)
uv pip install trio

# With conda
conda install -c conda-forge trio

Basic Example: Hello World

import trio

async def main():
    print("Hello from Trio!")

trio.run(main)

Concurrent Tasks with Nursery

import trio

async def fetch_page(url):
    print(f"Fetching {url}")
    await trio.sleep(1)  # Simulate I/O
    print(f"Done with {url}")

async def main():
    async with trio.open_nursery() as nursery:
        nursery.start_soon(fetch_page, "https://example.com/1")
        nursery.start_soon(fetch_page, "https://example.com/2")
        nursery.start_soon(fetch_page, "https://example.com/3")
    # All three fetches complete before reaching here
    print("All pages fetched!")

trio.run(main)

Timeout with Cancel Scope

import trio

async def slow_operation():
    await trio.sleep(10)
    return "completed"

async def main():
    with trio.move_on_after(5) as cancel_scope:
        result = await slow_operation()
        print(f"Result: {result}")

    if cancel_scope.cancelled_caught:
        print("Operation timed out after 5 seconds")

trio.run(main)

Echo Server Example

import trio

async def echo_server(server_stream):
    async for data in server_stream:
        await server_stream.send_all(data)

async def main():
    await trio.serve_tcp(echo_server, 8000)

trio.run(main)

Memory Channels

import trio

async def producer(send_channel):
    async with send_channel:
        for i in range(10):
            await send_channel.send(i)

async def consumer(receive_channel):
    async with receive_channel:
        async for value in receive_channel:
            print(f"Received: {value}")

async def main():
    send_channel, receive_channel = trio.open_memory_channel(0)
    async with trio.open_nursery() as nursery:
        nursery.start_soon(producer, send_channel)
        nursery.start_soon(consumer, receive_channel)

trio.run(main)

Ecosystem

Official python-trio Organization Projects

Third-Party Integrations

• httpx: Async HTTP client with Trio support
• asks: Async HTTP requests library inspired by requests
• trio-websocket: WebSocket client/server for Trio
• trio-asyncio: Interoperability layer with asyncio
• anyio: Async library abstraction supporting Trio and asyncio

Relevance to Claude Code Development

Direct Applications

1. Async Script Execution: Trio's structured concurrency could simplify async operations in Claude Code scripts that need parallel I/O (e.g., fetching multiple URLs, concurrent file operations).

2. Timeout Management: Cancel scopes provide elegant timeout handling for operations that might hang, useful for tool implementations that call external services.

3. Multi-Task Orchestration: Nursery pattern maps well to scenarios where multiple sub-operations must all complete before proceeding.

4. Error Propagation: Natural exception propagation through nurseries simplifies error handling in complex async workflows.

Patterns Worth Adopting

1. Structured Concurrency: The nursery pattern ensures no orphan tasks - all spawned work completes within its scope. This principle is valuable for any concurrent operation management.

2. Explicit Checkpoints: Static guarantees about where concurrency can interleave makes code review and reasoning about concurrent code tractable.

3. Unified Cancellation: Single cancellation mechanism (cancel scopes) vs separate APIs for different timeout scenarios.

4. Task Completion Guarantees: Nurseries guarantee all child tasks complete before exiting - prevents resource leaks and orphan operations.

5. Composable Cancel Scopes: Nesting timeouts naturally with predictable semantics.

Integration Opportunities

1. MCP Server Development: Trio could serve as the async runtime for Python MCP servers, providing cleaner concurrency than raw asyncio.

2. Tool Implementation: Tools that perform parallel operations (batch API calls, concurrent file processing) could use Trio's nurseries.

3. anyio Compatibility: Since anyio supports both Trio and asyncio, code can be written once and run on either runtime.

4. Testing: pytest-trio provides clean patterns for testing async code that could inform testing strategies for Claude Code extensions.

Comparison with asyncio

References

Research Method: Information gathered from GitHub API (repository metadata, releases, contributors), PyPI API (package info, download statistics), official documentation at trio.readthedocs.io, and README.rst from the repository.

Freshness Tracking

Review Triggers:

• Major version release (v1.0 or significant milestone)
• New structured concurrency features
• Breaking API changes
• Significant ecosystem growth (httpx, anyio adoption changes)
• Python version support changes
• New async patterns or primitives added