аннотации типов Python: Как перейти с mypy на ty: статическая проверка

Python поддерживает аннотации типов уже достаточно давно, начиная с версии 3.5. Однако сам интерпретатор Python не навязывает проверку типов. Чтобы проверить типы, нужно использовать внешние инструменты или IDE. Самым первым и, возможно, самым популярным является mypy.

Microsoft предлагает собственный инструмент статической проверки типов Python, который можно использовать в VS Code, под названием Pyright, а также существует менее известный инструмент статической проверки типов и языковой сервер (language server) под названием Pyrefly.

Новейший инструмент статической проверки типов — ty от Astral, создателей Ruff. Ty — быстрый инструмент статического анализа Python, написанный на Rust.

В этой статье вы узнаете, как переключить ваш проект на использование ty локально и в GitHub Actions.

Когда переход на ty действительно оправдан

Ty имеет смысл не во всех проектах подряд. Если у вас небольшой скрипт без CI, без жёстких требований к качеству типов и без команды, которая договорилась о стандартах, миграция может не дать заметной пользы. Но в кодовой базе, где уже используются аннотации типов, проверка в pull request и pre-commit-хуки, переход становится прагматичным решением: вы сохраняете дисциплину типизации и получаете более современный инструмент с хорошей скоростью работы.

Практически это особенно заметно в монорепозиториях и сервисах с несколькими пакетами. Там важно не только наличие инструмента проверки типов (type checker), но и то, насколько часто разработчики готовы запускать его локально. Чем быстрее инструмент, тем выше шанс, что его будут использовать до отправки кода в CI, а не только после красного билда. Именно здесь ty выглядит интересной заменой mypy.

По этой теме полезно отдельно посмотреть Составьте еженедельное расписание занятий, чтобы расширить контекст и сравнить подходы.

По этой теме полезно отдельно посмотреть Аннотации типов для декораторов в Python, чтобы расширить контекст и сравнить подходы.

Чем ty отличается от mypy при проверке аннотаций типов

Mypy долгое время был стандартом де-факто для статической проверки типов в Python, и эта роль остаётся заслуженной: экосистема вокруг него зрелая, документации много, а большинство команд уже знают, как с ним работать. У ty другая ставка. Он ориентирован на быстрый локальный цикл, современную экосистему Astral и более простой старт без большого количества исторических настроек.

На практике различия видны в трёх местах. Во-первых, в скорости обратной связи: быстрый запуск важен для разработчика так же, как быстрые unit-тесты. Во-вторых, в подходе к конфигурации: ty пока выглядит как более лёгкий входной порог, особенно если вам не нужен гигантский набор устаревших настроек. В-третьих, в ожиданиях команды: mypy часто уже встроен в привычки и пайплайны, поэтому миграция должна быть управляемой, а не импульсивной.

План миграции без боли для команды

Самая частая ошибка при переходе с одного инструмента проверки типов на другой — выключить старый инструмент в тот же день, когда включается новый. Намного безопаснее идти поэтапно.

Сначала зафиксируйте исходное состояние (baseline): какие ошибки сейчас ловит mypy, где стоят исключения и какие директории уже покрыты типами. Затем запустите ty локально на одной-двух директориях, которые лучше всего типизированы. Это даст реальную картину несовпадений без массового шума.

Следующий этап — параллельный запуск в CI. На короткий период полезно держать и mypy, и ty рядом: один остаётся источником истины, второй работает в режиме наблюдения (без блокировки сборки). Когда вы увидите, что ty стабильно даёт ожидаемые результаты, можно переносить его в обязательную проверку pull request. Такой порядок почти всегда вызывает меньше сопротивления у команды, потому что вы не меняете правила игры одномоментно.

Установка

Вы можете запускать ty через uvx, если не хотите его устанавливать, используя следующую команду в терминале:

uvx ty

Чтобы установить ty через uv, выполните команду:

uv tool install ty@latest

Если вы не хотите использовать uv, можно воспользоваться отдельным установщиком. Инструкции зависят от вашей платформы, лучше всего обратиться к документации по ссылке для последних сведений.

Примечание: технически ty также можно установить через pip или pipx.

Если вы уже используете uv для управления инструментами разработчика, установка через uv tool install обычно удобнее всего: версия фиксируется явно, а сам бинарник не смешивается с зависимостями конкретного проекта. Это особенно полезно в командах, где каждый разработчик должен получать одинаковое поведение линтера и инструмента проверки типов на локальной машине.

Запуск ty локально

После установки ty, его можно запускать следующими способами:

Запуск с uv

Запуск без установки:

uv run ty

Запуск ty напрямую:

uvx ty

Команда для проверки:

ty check

Конфигурация ty: настройка правил проверки аннотаций типов

В pyproject.toml или ty.toml можно изменить множество правил. Подробности в документации. Если вы раньше использовали mypy в строгом режиме, запуск ty с настройками по умолчанию будет похож.

Однако ty сейчас не выделяет отсутствующие аннотации типов. Если требуется обязательное добавление аннотаций, можно использовать flake8-annotations из Ruff.

Вот как включить flake8-annotations в вашем pyproject.toml:

(Добавьте "ANN" в конец списка правил, чтобы активировать их.)

На этом этапе полезно договориться о политике команды. Если ty отвечает за статическую проверку, а Ruff с flake8-annotations — за обязательность аннотаций, это нужно зафиксировать в CONTRIBUTING.md или в коротком internal RFC. Тогда у разработчиков не будет ощущения, что проверка «случайно» переехала из одного инструмента в другой.

Ещё один практический совет: не включайте строгие правила на весь репозиторий одним коммитом. Лучше начать с новых модулей или тех директорий, где типы уже поддерживаются в хорошем состоянии. Иначе переход превратится в большой cleanup-спринт, а не в управляемую инженерную миграцию.

Запуск ty в GitHub Actions: автоматическая проверка типов в CI

В файле .github/actions/ty.yml или в любом другом job GitHub Actions для проверки типов добавьте следующий код:

name: ty
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
jobs:
  build:
    if: github.event.pull_request.draft == false
    runs-on: self-hosted
    steps:
    - uses: actions/checkout@v3
    - name: Install Python
      uses: actions/setup-python@v4
      with:
        python-version: "3.12"
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install ty==0.0.7
    - name: Run ty
      run: ty check
      continue-on-error: false

Теперь при открытии pull request команда автоматически запускает ty. Версию Python и ty можно изменять согласно своим нуждам.

Для production-команд я бы добавил сюда ещё два правила. Первое: запускайте проверку только для изменённых пакетов или для заранее определённых директорий, если репозиторий большой. Второе: логируйте версию ty в самом job GitHub Actions, чтобы при обновлении инструмента было проще понять, откуда появились новые сообщения об ошибках.

Использование ty с pre-commit

Можно использовать различные конфигурации для pre-commit с ty, например, из всех перечисленных репозиториев.

Когда Astral добавит собственную поддержку pre-commit, конфигурации стоит обновить.

Пока можно взять первый из списка репозиторий и добавить его в ваш .pre-commit-config.yaml, чтобы при каждом локальном коммите запускалась проверка ty.

Связка pre-commit и CI особенно полезна тем, что снимает лишнюю нагрузку с ревью. Разработчик видит проблему до push, а reviewer не тратит время на обсуждение очевидных типовых несоответствий. Если вы внедряете ty в существующую команду, именно pre-commit часто становится самым заметным улучшением пользовательского опыта.

Что проверить после первого запуска ty

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

Полезно также сравнить, какие предупреждения исчезли по сравнению с mypy, а какие, наоборот, появились. Такой срез помогает решить, где ty уже можно сделать обязательным, а где пока лучше оставить переходный период. Чем прозрачнее вы объясните эти различия команде, тем меньше будет ощущения, что новый инструмент просто «навязали сверху».

Проверщики типов помогают находить тонкие ошибки в Python, но важно помнить запускать их автоматически, например, через CI/CD.

Желаю успешного кодинга и новых хороших практик!

Частые вопросы по переходу с mypy на ty

Нужно ли удалять mypy сразу после установки ty? Нет. Намного безопаснее держать оба инструмента параллельно хотя бы один-два спринта, пока вы не увидите, что ty покрывает ваши сценарии и не ломает процесс ревью.

Где лучше фиксировать настройки ty: в pyproject.toml или отдельном файле? Если проект уже централизует конфигурацию в pyproject.toml, удобнее оставить всё там. Отдельный ty.toml имеет смысл, когда вы хотите изолировать настройки инструмента и не смешивать их с конфигурацией Ruff, pytest и других утилит.

Чем дополнять ty, если команде важны обязательные аннотации? Сам ty не закрывает этот сценарий полностью. Для контроля отсутствующих аннотаций удобно подключать Ruff с правилами flake8-annotations, тогда вы получите и проверку типов, и проверку дисциплины типизации.