Trio

Warnings

• breaking The behavior of `trio.move_on_after` and `trio.fail_after` changed in v0.27.0. Previously, deadlines were set relative to initialization time; they now refer to the time of entering the context manager.
  Fix: If you relied on the old behavior, use `trio.move_on_at(trio.current_time() + ...)` instead to explicitly set a deadline relative to the current time.
• deprecated `trio.testing.RaisesGroup` and `trio.testing.Matcher` have been deprecated.
  Fix: Use `pytest.RaisesGroup` and `pytest.RaisesExc` from Pytest as their replacements.
• gotcha Spawning 'fire-and-forget' tasks without a `trio.open_nursery()` can lead to leaked tasks, unhandled exceptions, and difficult program shutdowns. Trio's core principle is structured concurrency, meaning tasks should have a clear parent and lifetime.
  Fix: Always use `async with trio.open_nursery() as nursery:` and spawn tasks with `nursery.start_soon()` or `nursery.start()`. The nursery ensures all child tasks complete (or are cancelled) before the `async with` block exits.
• gotcha Trio's cancellation mechanism is explicit and propagated. Any `await` call to a function in the `trio` namespace acts as a checkpoint and can raise a `trio.Cancelled` exception if an enclosing scope is cancelled. Failure to handle `Cancelled` correctly can lead to resource leaks or unexpected program termination.
  Fix: Design async functions to be aware of and handle `trio.Cancelled` exceptions, especially when managing resources, to ensure proper cleanup.
• gotcha Calling long-running, blocking I/O operations inside `trio.run_in_worker_thread` without an explicit exit mechanism for the worker can prevent `Ctrl+C` from cleanly shutting down the application, as Trio's cancellation doesn't directly apply to OS threads.
  Fix: Ensure that code executed in worker threads periodically checks for a cancellation signal (e.g., via a shared event or flag) and exits gracefully, or uses I/O operations that are themselves interruptible.
• gotcha Iterating over an `@as_safe_channel`-derived `ReceiveChannel` could previously raise `trio.BrokenResourceError` if the channel was closed by another task. While a fix was implemented in v0.32.0, improper handling of async generators and channels remains a potential footgun if not following best practices.
  Fix: For async generators, use `@trio.as_safe_channel` (introduced in v0.30.0) to ensure safe and structured behavior. Always design channel usage with clear close semantics.

Install

• pip install trio Install stable version

Imports

• trio

  import trio

  The primary import for accessing Trio's API.
• open_nursery

  import trio; async with trio.open_nursery() as nursery:

  Used for structured concurrency to manage child tasks.
• run

  import trio; trio.run(async_main_function)

  The entry point to run a Trio async function from synchronous code.

Quickstart

This example demonstrates structured concurrency with `trio.run` and `trio.open_nursery`. It launches two child tasks concurrently, and the `nursery` ensures that `main` waits for both to complete before exiting. Tasks use `trio.sleep` for non-blocking delays.

import trio
import os

async def child_task(name, delay):
    print(f"{name}: started! Sleeping for {delay} seconds.")
    await trio.sleep(delay)
    print(f"{name}: exiting!")

async def main():
    print("main: started")
    async with trio.open_nursery() as nursery:
        nursery.start_soon(child_task, "child1", 1)
        nursery.start_soon(child_task, "child2", 1)
    print("main: all children exited")

if __name__ == "__main__":
    # In a real application, you might use an environment variable for configuration
    # e.g., AUTH_TOKEN = os.environ.get('TRIO_AUTH_TOKEN', '')
    trio.run(main)