Чекеры в бою: сужение типов, строгость, зараза Any и mypy против pyright

Сужение: что чекер реально может доказать

Чекер — это прувер над вашим control flow. Видя value: str | bytes | None, он отслеживает, как каждая ветка ужимает объединение: if value is None: return устраняет None до конца функции; isinstance(value, bytes) расщепляет остаток; морж if (m := pattern.match(s)): сужает m до Match[str] внутри блока; match сужает по веткам case. Когда встроенное сужение не видит сквозь ваши хелперы, его учат: TypeGuard (PEP 647) объявляет, что булева функция доказывает тип в своей истинной ветке, а TypeIs (PEP 742, Python 3.13) — более воспитанный преемник, сужающий обе ветки:

from typing import Any, TypeGuard

def is_str_list(xs: list[Any]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in xs)

def handle(value: str | bytes | None) -> str:
    if value is None:
        return ""
    if isinstance(value, bytes):
        reveal_type(value)   # note: Revealed type is "bytes"
        return value.decode()
    reveal_type(value)       # note: Revealed type is "str"
    return value

reveal_type() — отладчик всего этого: фиктивная функция, понятная только чекеру (в старых Python она падает в рантайме; с 3.11 настоящая есть в typing), печатающая, кем чекер считает значение ровно на этой строке. Когда чекер отвергает код, который вы «точно знаете, что корректен», продуктивный ход — не спорить, а вставить reveal_type и обнаружить, что в объединении всё ещё живёт член, который вы якобы устранили. Острый край TypeGuard: чекер слепо доверяет вашей реализации. Гард, возвращающий True для неверной формы, — дырка, пробитая в доказательстве, причём с полной уверенностью чекера за спиной.

Any — зараза; строгость — карантин

Прежде чем записывать «80% покрытия аннотациями» в успех, спросите себя: откуда данные реально входят в кодовую базу? Если на дне цепочки вызовов сидит сторонний клиент или нетипизированный хелпер, эти восемьдесят процентов могут не покрывать почти ничего.

Any (специальный тип, совместимый со всем в обе стороны и отключающий проверку) совместим со всем в обе стороны — и он расползается. Значение из нетипизированной библиотеки — Any; проиндексируйте его, сложите с чем-то, передайте дальше — и каждый результат тоже Any. Пути кода, тронутые Any, попросту не проверяются, выглядя при этом неотличимо от проверенных. Вот почему «у нас 80% покрытия аннотациями» может значить куда меньше, чем звучит: один нетипизированный клиент на дне цепочки вызовов тихо превращает целые модули обратно в динамический Python. Флаги строгости — карантин. --strict у mypy связывает главные: --disallow-untyped-defs (каждая функция аннотирована), --disallow-any-generics (никаких голых list), --warn-return-any, а неявный Optional современный mypy отвергает уже по умолчанию — -> bool, возвращающий None, из Хука умирает прямо там. Режим strict у pyright — эквивалент, плюс диагностики в духе reportUnknownMemberType, которые показывают Any, утекающий из библиотек, вместо молчаливого принятия. Полный strict на легаси за один день не включает никто; рабочий паттерн — помодульный храповик: strict для новых и пограничных модулей, basic для остального, и конфиг только затягивается.

mypy против pyright и превращение доказательства в CI-гейт

Два продовых чекера согласны в ядре, но полезно расходятся. mypy — референсная реализация: на Python, медленнее на больших кодовых базах (демон dmypy делает тёплые перепроверки быстрыми), с системой плагинов, понимающей магию Django и SQLAlchemy, — в этих стеках это часто решающий фактор. pyright — чекер Microsoft на TypeScript, движок внутри Pylance/VS Code: заметно быстрее на больших репозиториях (полные прогоны, занимающие у mypy минуты, обычно укладываются в секунды или десятки секунд), с watch-режимом и ощутимо более сильным выводом типов — pyright выводит типы возврата неаннотированных функций и проверяет их тела, тогда как mypy по умолчанию считает неаннотированные функции Any и пропускает их. Одно это различие означает, что pyright находит реальные баги в коде, который mypy вообще не читает, — и оно же объясняет волну новых ошибок в первый день внедрения pyright. Честный совет: любой из двух радикально лучше, чем ничего; pyright — за скорость и вывод, mypy — за плагинозависимые ORM; гонять оба разумно, потому что они ловят непересекающиеся проблемы. Какой бы вы ни выбрали, он обязан быть CI-гейтом — «чекер только на ноутбуке» и есть способ получить Хук. Стандартная схема: прогон на каждом PR с кешированием, падение сборки на любой новой ошибке и запиненная версия чекера, чтобы апгрейды (добавляющие проверки) приезжали осознанными PR, а не внезапно красной сборкой.