Type hints и mypy: сетка безопасности без изменения семантики языка

Утиная типизация гибка, но не бесплатна. Если функция ожидает итерируемое со строками, а ей передали [1, 2, 3] — протокол итерации соблюдён, и ошибка вылезет глубоко внутри, на первом .upper(). Здесь вступают аннотации типов и статический анализ.

Аннотации типов (type hints, PEP 484) выглядят похоже на сигнатуры C:

def greeting(name: str) -> str:
    return 'Hello ' + name

Но по семантике это совсем другая вещь: аннотации — это метаданные, которые CPython во время выполнения в общем случае не проверяет и не использует для диспетчеризации. greeting(123) спокойно дойдёт до тела функции и упадёт (или не упадёт) уже по факту исполнения операции.

Отсюда первая экспертная ошибка C-программиста: увидев type hints, он расслабляется, считая, что «теперь Python типизирован, как C». Это неверно ровно так же, как комментарий не гарантирует, что код ему соответствует. Аннотация — декларация намерения для человека и для внешнего инструмента.

Этим инструментом обычно является mypy (аналоги — pyright, pyre). Он читает те же аннотации и статически, до запуска, проверяет согласованность типов по всей кодовой базе — ту работу, которую в C бесплатно делал компилятор, но как отдельный, осознанно запускаемый шаг. Не запускаете mypy в CI или перед коммитом — аннотации остаются документацией, не защищающей ни от чего в runtime.

graph TD
    A["1. Пишем код с аннотациями"] --> B{"2. Запускаем mypy"}
    B -->|"ошибки найдены"| C["3. mypy: Argument 1 has incompatible type int; expected str"]
    C --> D["4. Исправляем код"]
    D --> A
    B -->|"ошибок нет"| E["5. Запускаем python my_script.py"]

Не теряется ли при этом гибкость протоколов? Нет: модуль typing даёт абстрактные типы, описывающие поведение, а не конкретные классы:

• Iterable[T] — всё, что можно итерировать, отдавая элементы типа T;
• Sequence[T] — есть длина и доступ по индексу (__len__, __getitem__);
• Mapping[K, V] — поведение словаря;
• Protocol — формальное описание «утиного типа»: любой класс с нужными методами подходит структурно, без наследования.

from typing import Iterable

def process_strings(items: Iterable[str]) -> None:
    for item in items:
        print(item.upper())   # mypy знает, что item — str

process_strings(["a", "b"])   # OK
process_strings(("c", "d"))   # OK
# process_strings([1, 2, 3])
# error: List item 0 has incompatible type "int"; expected "str"

Практическая связка для C-привычки к строгой типизации:

1. Аннотируйте публичные функции и границы модулей — там контракт ценнее всего.
2. Запускайте mypy отдельным шагом, аналогично gcc -Wall -Werror: до тестов, в CI, локально перед коммитом.
3. Не путайте прохождение mypy с отсутствием runtime-ошибок: mypy не выполняет код и не видит динамику (getattr, setattr, eval, монки-патчинг, данные из json.loads без аннотаций).

def clamp(value: int, low: int, high: int) -> int:
    if value < low:
        return low
    if value > high:
        return high
    return value

clamp("abc", 0, 10)

error: Argument 1 to "clamp" has incompatible type "str"; expected "int"

flowchart TD
    A[Код с аннотациями типов] --> B{Запущен mypy?}
    B -->|да| C[Статическая проверка согласованности типов до запуска]
    C --> D[Ошибка найдена до исполнения, как в C]
    B -->|нет| E[Аннотации игнорируются интерпретатором]
    E --> F[Проверка типов только в runtime, как в уроке 1]