{"id":4292,"library":"trio-typing","title":"Trio Typing","description":"trio-typing provides static type checking support for Trio and related projects. It offers PEP 561 typing stubs for `trio`, `outcome`, and `async_generator`, along with a `mypy` plugin to enhance type checking capabilities for asynchronous code. The current version is 0.10.0, and it follows the release cadence of the broader Trio ecosystem.","status":"active","version":"0.10.0","language":"en","source_language":"en","source_url":"https://github.com/python-trio/trio-typing","tags":["async","trio","typing","type hints","mypy","static analysis","concurrency"],"install":[{"cmd":"pip install trio-typing","lang":"bash","label":"For runtime use (stubs only)"},{"cmd":"pip install trio-typing[mypy]","lang":"bash","label":"For static type checking with Mypy"}],"dependencies":[{"reason":"Provides the core asynchronous framework that trio-typing provides type hints for. Requires trio v0.11.0 or later for full stub compatibility.","package":"trio","optional":false},{"reason":"Required to use the Mypy plugin for enhanced static analysis of Trio code. Installed via the `[mypy]` extra.","package":"mypy","optional":true},{"reason":"trio-typing provides type stubs for this package.","package":"outcome","optional":false},{"reason":"trio-typing provides type stubs for this package.","package":"async_generator","optional":false}],"imports":[{"note":"Type hint for objects passed to nursery.start().","symbol":"TaskStatus","correct":"from trio_typing import TaskStatus"},{"note":"Type hint for asynchronous generators. On Python 3.6+, this re-exports typing.AsyncGenerator.","symbol":"AsyncGenerator","correct":"from trio_typing import AsyncGenerator"},{"note":"As of Trio 0.12.0, the actual Trio Nursery class is publicly exported directly from the trio package, and should be imported from there for type hinting.","wrong":"from trio_typing import Nursery","symbol":"Nursery","correct":"from trio import Nursery"},{"note":"Mypy plugin for Trio-specific type checking enhancements.","symbol":"plugin","correct":"plugins = trio_typing.plugin # in mypy.ini"}],"quickstart":{"code":"import trio\nfrom trio_typing import TaskStatus\nfrom typing import TypeVar\n\nT = TypeVar(\"T\")\n\nasync def child_task(value: T, *, task_status: TaskStatus[T]) -> None:\n    \"\"\"An asynchronous task that signals its start status.\"\"\"\n    print(f\"Child task received: {value}\")\n    task_status.started(f\"Processed: {value}\") # Type-checked by trio-typing\n    await trio.sleep(0.1)\n\nasync def main() -> None:\n    \"\"\"Main function demonstrating nursery.start with type hints.\"\"\"\n    print(\"Starting main...\")\n    async with trio.open_nursery() as nursery:\n        # mypy will check that 'child_task' matches the expected signature for nursery.start\n        result = await nursery.start(child_task, \"hello\")\n        print(f\"Nursery start returned: {result}\")\n    print(\"Main finished.\")\n\nif __name__ == \"__main__\":\n    # To enable mypy checks, ensure you have mypy installed with trio-typing[mypy]\n    # and 'plugins = trio_typing.plugin' in your mypy.ini file.\n    # Example mypy.ini:\n    # [mypy]\n    # plugins = trio_typing.plugin\n    # \n    # Then run: mypy your_script_name.py\n    trio.run(main)\n","lang":"python","description":"This example demonstrates how to use `trio_typing.TaskStatus` for type-hinting tasks started with `trio.Nursery.start()`. It also implicitly shows how `trio.Nursery` is imported directly from `trio`. To leverage the full type-checking power, ensure you install `trio-typing[mypy]` and configure the plugin in your `mypy.ini`."},"warnings":[{"fix":"Upgrade Mypy to version 1.0 or greater (`pip install --upgrade mypy`).","message":"Versions of trio-typing 0.10.0 and later require Mypy 1.0 or newer due to changes in Mypy's plugin API.","severity":"breaking","affected_versions":"0.10.0+"},{"fix":"Change your import statement from `from trio_typing import Nursery` to `from trio import Nursery`.","message":"The `Nursery` type should now be imported directly from the `trio` package (`from trio import Nursery`). Importing `Nursery` from `trio_typing` is deprecated.","severity":"deprecated","affected_versions":"Since Trio 0.12.0"},{"fix":"Perform static type checking in a CPython environment.","message":"While Trio itself supports both CPython and PyPy runtimes, static type checking with `mypy` and `trio-typing` must currently occur on CPython environments, due to limitations of `mypy`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adjust your project's dependency management to separate runtime and development/type-checking dependencies.","message":"When listing dependencies for a library that uses `trio_typing`, avoid specifying `trio-typing[mypy]` in `install_requires`. This would needlessly add a `mypy` dependency to every application transitively depending on your library. Instead, list `trio-typing` as a regular dependency and specify `mypy` (and `trio-typing[mypy]`) in development-specific dependencies (e.g., `requirements-dev.txt` or `pyproject.toml`'s `[project.optional-dependencies.dev]`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}