Python: аннотации типов и mypy

Коротко: Аннотации типов (type hints) записывают в код Python ожидаемые типы параметров, возвращаемых значений и переменных. Python их не навязывает, но инструменты вроде mypy и редакторы проверяют их.

Подробнее: Python остаётся динамически типизированным. Подсказки служат людям и инструментам: лучшее автодополнение, ранние сообщения об ошибках, более читаемые интерфейсы.

Подробности

• Основная форма: def price(net: float, tax: float = 0.19) -> float: и name: str = "Anna".
• Контейнеры: list[int], dict[str, float], tuple[int, str], set[str] (напрямую с Python 3.9, раньше typing.List и т. д.).
• Optional и объединение: str | None (с 3.10) или Optional[str]. Говорит: может быть None, поэтому проверяйте перед использованием.
• Ещё: Callable[ [int], str ] для функций, TypedDict для словарей с фиксированными ключами, Protocol для структурных интерфейсов («утиная типизация» с проверкой), Any как лазейка.
• mypy: mypy file.py статически проверяет подсказки и сообщает о противоречиях, например при передаче str вместо int. Альтернативы: pyright (в Pylance), pytype.
• Постепенно: Можно аннотировать отдельные файлы или функции. Неаннотированный код обрабатывается снисходительно.
• Во время выполнения: Библиотеки вроде Pydantic или FastAPI читают подсказки и проверяют входные данные.
• Предел: Подсказки ничего не гарантируют во время выполнения.

См. также: системы типов и вывод типов, линтеры, форматтеры и проверка типов