Аннотации типов в Python: type hints и mypy

Коротко: Type hints описывают, какие типы функции ожидают и возвращают; Python сам их не проверяет, но редакторы и инструменты вроде mypy находят ошибки до запуска.

Подробнее: Python — динамически типизированный язык: типы определяются во время выполнения. Начиная с Python 3.5 можно указывать аннотации типов. Они — документация и помощь в проверке, но не меняют поведение во время выполнения.

Подробности

Основы

def greet(name: str, count: int = 1) -> str:
    return ("Hello " + name + "! ") * count
prices: dict[str, float] = {"Game": 12.5}
names: list[str] = []
coordinate: tuple[int, int] = (3, 4)

Современная запись с 3.9/3.10: list[int], dict[str, int], int | None (вместо Optional[int]), X | Y для объединений. Возвраты None: -> None. Для функций без возврата не используйте -> any.

Полезные типы

• Optional[T] / T | None: значение или ничего.
• Union, Literal["a", "b"], Any (отключает проверку).
• Callable[[int], str] для функций, Iterable, Sequence, Mapping.
• TypedDict, NamedTuple, dataclass, Protocol (структурная типизация/«утиная типизация» с проверкой).
• Generic/TypeVar для обобщённых функций/классов: def first(xs: list[T]) -> T.
• Final, ClassVar, Self, override.
• Псевдонимы типов: Price = float, type Point = tuple[int, int] (3.12).

Проверка через mypy/pyright

pip install mypy
mypy my_file.py

mypy --strict строг; вводите шаг за шагом (постепенная типизация). Редакторы (VS Code с Pylance/pyright, PyCharm) показывают ошибки вживую. Пример: greet(5) сообщает «argument 1 has incompatible type int; expected str» до запуска программы. Запускайте в CI. Библиотеки без типов: пакеты types-… (заглушки). # type: ignore используйте экономно.

Польза и пределы

• Преимущества: меньше ошибок (ошибки None!), лучше автодополнение, читаемость, безопасность рефакторинга; основа фреймворков вроде FastAPI/pydantic (типы используются во время выполнения для валидации).
• Пределы: во время выполнения ничего не проверяется; неверная аннотация лжёт; очень динамичный код трудно типизировать.
• Практика: аннотируйте публичные функции и интерфейсы, небольшие внутренние скрипты не обязательно.
• Сравнение: TypeScript (JS), Java/C# (статические) – Python типизирован необязательно.
• Экзамен/обучение: находите ошибки типов до запуска; проверяйте через reveal_type(x) в mypy.

См. также: TypeScript, Линтеры, форматировщики и проверяющие типы