README.md

mypy-typing-asserts

Adds the ability to assert types when typechecking to mypy.

assert_type[MyType[tuple[int, ...]]](myobject.attribute)

Support

mypy-typing-asserts is supported in mypy >= 0.700.

For similar functionality in pyright, use reveal_type(expression, expected_type=...). (See this discussion). (Supported in version 1.1.211+)

For similar functionality in pytype, use assert_type. (See the docs)

Installation

mypy-typing-asserts should be installed in to the same environment as your typechecker.

It can be installed by running pip install mypy-typing-asserts.

Alternatively if you're using poetry, poetry add -D mypy-typing-asserts.

Usage

To use, just call assert_type providing a type-parameter and an argument. This will assert that the type of the argument is exactly the same type as the type-parameter (type-hierarchies are not traversed) when typechecking (assuming you have enabled this functionality).

from mypy_typing_asserts import assert_type

...

assert_type[MyType](my_expression)

# `assert_type` also returns the argument (but does no runtime checking)
var = assert_type[int](my_function())

Note that you may need to hide your import and usage behind if typing.TYPE_CHECKING if the environment you're running the code in isn't the same that you typecheck in.

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from mypy_typing_asserts import assert_type

...

if TYPE_CHECKING:
    assert_type[MyType](my_expression)

Pitfalls

This plugin only gets executed for code that is being typechecked. Dependening on your configuration, yopur typechecker might be skipping function bodies (e.g. mypy will skip unannotated function bodies by default unless --check-untyped-defs is enabled).

If you're putting the assert_type calls inside a pytest test, make sure to annotate the -> None return type to avoid this!

Enabling the mypy plugin

In your mypy config, add mypy_typing_asserts.mypy_plugin to your plugins declaration.

See mypy's documentation

Alternatives

All of the alternatives today ensure types are deduced correctly by running mypy in a subprocess, which isn't always feasible or ideal. These include:

• mypy-test - standalone mypy wrapper
• pytest-mypy-plugins - pytest plugin, test cases described in a YAML file.
• pytest-mypy-testing - pytest plugin, tests are described like pytest test cases (but they actually don't get run).