trio-typing: static typing for Trio and related projects
This repository provides:
- PEP 561 typing stubs packages for the Trio project packages:
- A package
trio_typingcontaining types that Trio programs often want to refer to (
TaskStatus[T]) and a mypy plugin that smooths over some limitations in the basic type hints.
To type-check code that uses
trio-typing, you need CPython 3.5.2
or later. (Mypy requires 3.5.2+, and its dependency
doesn't support PyPy.) We test on Linux using the latest releases
from the 3.5, 3.6, and 3.7 branches, as well as 3.8-dev nightly. We're
not knowingly doing anything OS-specific, so other OSes should work
You can run code that uses
trio-typing on any platform
supported by Trio, includng PyPy and CPython 3.5.0 and 3.5.1.
Type checkers other than Mypy are not supported, but might work. Experience reports and patches to add support are welcome.
pip install -U trio-typing
Enable the plugin in your
mypy.ini (optional, but recommended):
[mypy] plugins = trio_typing.plugin
Start running mypy on your Trio code! You may want to import some typing
TaskStatus; see below
for more details.
What's in the box?
The stubs packages provide types for all public non-deprecated APIs of
async_generator, as of the release date
of the corresponding
trio-typing distribution. You don't need to
explicitly configure these; just say
import trio (for example)
and mypy will know to look in
trio-stubs for the type information.
trio_typing package provides:
- Names for two important types that Trio keeps anonymous:
Tis the type of the value the task provides to be returned from
nursery.start()). These are implemented as ABCs, and the actual private types inside Trio (like
trio._core._run.Nursery) are registered as virtual subclasses of them. So, you can't instantiate the
nurseryis a Trio nursery object does return True.
- A backport of
typing.AsyncGenerator[YieldT, SendT]to Python 3.5. (
YieldTis the type of values yielded by the generator, and
SendTis the type of values it accepts as an argument to
asend().) This is an abstract class describing the async generator interface:
aclose, and the
ag_*introspection attributes. On 3.6+,
trio_typing.AsyncGeneratoris just a reexport of
CompatAsyncGenerator[YieldT, SendT, ReturnT], a name for the otherwise-anonymous concrete async generator type returned by
@async_generatorfunctions. It is a subtype of
AsyncGenerator[YieldT, SendT]and provides the same methods. (Native async generators don't have a
ReturnT; it is only relevant in determining the return type of
- A few types that are only useful with the mypy plugin:
SendType[T], and the decorator
trio_typing.plugin mypy plugin provides:
Argument type checking for functions decorated with
@asynccontextmanager(either the one in
async_generatoror the one in 3.7+
Inference of more specific
trio.Path.open()return types based on constant
await trio.open_file("foo", "rb", 0)returns an unbuffered async file object in binary mode and
await trio.open_file("bar")returns an async file object in text mode
Signature checking for
task_status.started()with no arguments, so it raises an error if the
task_statusobject is not of type
Boilerplate reduction for functions that take parameters
(fn, *args)and ultimately invoke
fn(*args): just write:
from mypy_extensions import VarArg @trio_typing.takes_callable_and_args def start_soon( async_fn: Callable[[VarArg()], Awaitable[T]], *args: Any, other_keywords: str = are_ok_too, ): # your implementation here
start_soon(async_fn, *args)will raise an error if
async_fn(*args)would do so. You can also make the callable take some non-splatted arguments; the
*argsget inserted at whatever position in the argument list you write
The above example will always fail when the plugin is not being used. If you want to always pass in such cases, you can use a union:
@trio_typing.takes_callable_and_args def start_soon( async_fn: Union[ Callable[..., Awaitable[T]], Callable[[VarArg()], Awaitable[T]], ], *args: Any, other_keywords: str = are_ok_too, ): # your implementation here
Without the plugin, this type-checks fine (and allows inference of
T), since any callable will match the
Callable[..., Awaitable[T]]option. With the plugin, the entire union will be replaced with specific argument types.
Note: due to mypy limitations, we only support a maximum of 5 positional arguments, and keyword arguments can't be passed in this way;
nursery.start_soon(functools.partial(...))will pass the type checker but won't be able to actually check the argument types.
Mostly-full support for type checking
@async_generatorfunctions. You write the decorated function as if it returned a union of its actual return type, its yield type wrapped in
YieldType, and its send type wrapped in
from trio_typing import YieldType, SendType @async_generator async def sleep_and_sqrt() -> Union[None, SendType[int], YieldType[float]]: next_yield = 0.0 while True: amount = await yield_(next_yield) # amount is an int if amount < 0: return None await trio.sleep(amount) next_yield = math.sqrt(amount) # prints: CompatAsyncGenerator[float, int, None] reveal_type(sleep_and_sqrt())
@async_generatorfunction are type-checked based on these declarations. If you leave off either the yield type or send type, the missing one is assumed to be
None; if you leave off both (writing just
async def sleep_and_sqrt() -> None:, like you would if you weren't using the plugin), they're both assumed to be
Note the explicit
return None; mypy won't accept
returnor falling off the end of the function, unless you run it with
- Calls to variadic Trio functions like
nursery.start_soon(), and so on, only can type-check up to five positional arguments. (This number could be increased easily, but only at the cost of slower typechecking for everyone; mypy's current architecture requires that we generate overload sets initially for every arity we want to be able to use.) You can work around this with a
# type: ignorecomment.
outcome.acapture()currently don't typecheck their arguments at all.
Running the tests
trio-typing comes with a fairly extensive testsuite; it doesn't test all
the mechanical parts of the stubs, but does exercise most of the interesting
plugin behavior. You can run it after installing, with:
pytest -p trio_typing._tests.datadriven --pyargs trio_typing
Your choice of MIT or Apache 2.0.