Мой небольшой список источников по type hints в Python, которые я использую в повседневной практике.

Относительно недавно я сменил проект. Теперь я работаю над DWH и ETL‑процессами. Проект большой: в нём сравнимое количество кода с предыдущим, но разработчиков гораздо больше. Я убеждён, что для этого проекта подсказки типов даже нужнее. Дело не только в количестве разработчиков.

Особенность DWH/ETL‑проектов — наличие разнообразных источников, мест хранения и потребителей данных. Отсюда довольно сильная фрагментированность проекта. И если не добавить «клея», он развалится на отдельные скрипты.

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

Меня попросили собрать список из самых необходимых и полезных в повседневной практике ресурсов по подсказкам типов в Python. Особые требования к этому списку:

  • минимальное количество ссылок;
  • только то, что можно использовать в ежедневной работе;
  • максимально коротко и сжато (вот тут я провалился и не нашёл практически ничего: все ссылки ведут на довольно длинные статьи и документацию).

Вот мой список:

Огромный учебник от Real Python. Покрывается весь спектр вопросов, связанных с типами: от теории до настройки и запуска mypy. Это действительно полный гид по типам в Python — лучшее место для старта. Из минусов этого ресурса: он местами излишне многословен.

Подсказки с примерами описаний типов от создателей mypy. Очень удобно пользоваться: покрыты все базовые случаи с примерами. Когда я только начинал знакомиться с типами, заглядывал сюда через раз. Но тут только базовые простые примеры: если нужно что‑то продвинутое, то здесь этого нет.

Документация Python — одна из причин моей любви к языку. Документация для библиотеки typing — выше всяких похвал. Большая часть вопросов решается здесь. Зачастую надо полистать её немного, чтобы найти подходящий паттерн для описания типа в том или ином случае.

Иногда не хватает документации — тогда наступает время PEP 484 и PEP 483. В моей практике это вообще единственные PEP, в которые я заглядываю после их принятия — для поиска решения текущих задач. Они бывают очень полезны для прояснения логики, лежащей в основе системы подсказок типов. Без этого бывает сложно найти подходящую идею, как описать ту или иную часть кода.

Пожалуй, это все ссылки, которые я использую с завидной регулярностью. Иногда по поводу особо сложных случаев приходится заглядывать на Stack Overflow. Но, как обычно со Stack Overflow, голову выключать не стоит: иногда правильный и подходящий ответ — далеко не самый популярный или выбранный правильным.

Ничего по этим ссылкам нет по поводу внедрения подсказок в существующем проекте. Я об этом писал в конце 2017 года. Могу только сослаться на эту статью: Как внедрить mypy в проекте на Python 2.7.