Тайп-хинты как система: объединения, TypedDict, Literal и типизация границ в первую очередь

Что рантайм на самом деле делает с хинтом: ничего

Именно это различие и объясняет, почему баг из Hook три года оставался незамеченным. Как только вы поймёте, что рантайм с аннотацией делает — а чего не делает — стратегия «типизируйте сначала границы» перестанет быть советом и станет очевидностью.

CPython вычисляет аннотации и складывает их в словарь __annotations__ (встроенный словарь аннотаций функции) — на этом всё. def f(x: int) -> str спокойно примет список и вернёт None; никакой проверки, никакого приведения, никакого предупреждения и практически нулевая цена на вызов. Это сознательное решение (PEP 484 не зря называет типы «хинтами»): язык остаётся динамическим, а контроль делегирован внешним инструментам — mypy, pyright, вашей IDE. Следствие режет в обе стороны. Ничего не ломается, если хинты неверны, — поэтому непроверяемые хинты гниют во враньё вроде -> User из Хука. Но поскольку аннотации — это интроспектируемые данные, рантайм-фреймворки читают их намеренно: pydantic строит из них валидаторы, FastAPI выводит парсинг запросов и OpenAPI-схемы, dataclasses — поля. Один синтаксис, два потребителя — статические чекеры, которые хинтам доверяют, и рантайм-библиотеки, которые их исполняют, — и путать их между собой — классическая ловушка новичка: запись x: int валидирует x не больше, чем комментарий.

Словарь системы: объединения, дженерики, TypedDict, Literal, Annotated

Прежде чем смотреть на синтаксис: прикиньте, сколько анонимных словарей гуляет по вашему сервису без имён и без проверенных форм. Каждый — контракт, живущий только в чьей-то голове. Всё, что описано ниже, существует ровно затем, чтобы эти контракты записать и отдать на проверку чекеру.

Современный синтаксис хинтов (Python 3.10+) достаточно компактен, чтобы использовать его повсюду. X | Y (PEP 604) заменяет Optional[X] и Union[X, Y]; встроенные коллекции параметризуются напрямую — list[int], dict[str, Decimal] — без импортов typing.List. Рабочие лошадки реальных кодовых баз — типы формы:

from typing import Annotated, Literal, TypedDict

class Charge(TypedDict):
    amount_cents: int
    currency: Literal["usd", "eur"]   # only these two strings type-check
    customer_id: str

class ChargeWithMeta(Charge, total=False):
    idempotency_key: str              # optional key: may be absent

UserId = Annotated[str, "uuid4 from users.id"]  # extra metadata, same type

def settle(charge: Charge, retries: list[int] | None = None) -> bool:
    if charge["currency"] == "eur":   # checker knows the literal set
        ...
    return True

TypedDict — самый недооценённый инструмент в легаси: он даёт имя и проверяемую форму анонимным словарям, которые текут через любой Python-сервис, не меняя ни байта в рантайме — Charge остаётся обычным dict, так что ни один вызов не ломается. Literal превращает строковые флаги-режимы в замкнутые множества: settle(..., currency="usdd") становится падением сборки, а не KeyError в чужом леджере в три часа ночи. Annotated прикрепляет метаданные (единицы измерения, правила валидации), которые потребляют pydantic и FastAPI, тогда как чекеры видят базовый тип. Честная оговорка: TypedDict проверяет ключи и типы значений, но по умолчанию не лишние ключи, и не спасёт от словаря, собранного руками с опечаткой в непроверяемой точке вызова — покрытие ровно настолько хорошо, насколько большую часть графа вызовов видит чекер.

Постепенная типизация легаси: сначала границы

Нетипизированный сервис на 100 тысяч строк нельзя типизировать одним героическим спринтом — попытка породит PR «перелопатить всё», который никто не отревьюит. Работающая стратегия — постепенная типизация от границ внутрь. Сначала типизируйте края: HTTP-хендлеры, функции доступа к БД, консьюмеры очередей, публичные функции каждого пакета — места, где данные входят и выходят, потому что именно там неверная форма наносит максимальный урон и именно там TypedDict или dataclass документируют контракт, от которого зависят другие команды. Внутренние хелперы поначалу могут оставаться без аннотаций: чекер считает неаннотированные функции Any и пропускает их, так что типизированная поверхность растёт без ложных тревог. Дальше — храповик: фиксируйте строгость помодульно в конфиге (секции per-module у mypy, execution environments у pyright), чтобы уже типизированные модули не могли регрессировать, и требуйте аннотации во всём новом коде. Команды, идущие этим путём, видят отдачу быстро — чекер начинает ловить настоящие баги (забытый None, перепутанный порядок аргументов, опечатки в ключах словаря) уже на первых пограничных модулях, задолго до внушительного покрытия. Антипаттерн — посыпать хинтами внутренности, пока I/O-край всё ещё гоняет сырые словари: получите шум аннотаций без ценности контракта.