typeshed

напечатанный

О

Typeshed содержит внешние аннотации типов для стандартной библиотеки Python и встроенных функций Python, а также сторонние пакеты, предоставленные людьми, не входящими в эти проекты.

Эти данные можно, например, использовать для статического анализа, проверки типов, вывода типов и автодополнения.

Информацию о том, как использовать typeshed, читайте ниже. Информацию для участников можно найти на сайте CONTRIBUTING.md. Пожалуйста, прочтите его перед отправкой запросов на включение; не сообщайте о проблемах с аннотациями к проекту, для которого предназначены заглушки, а вместо этого сообщите о них здесь, в typeshed.

Дополнительную документацию по файлам-заглушкам, typeshed и системе типизации Python в целом также можно найти по адресу https://typing.readthedocs.io/en/latest/.

Typeshed поддерживает версии Python от 3.8 до 3.13.

С использованием

Если вы просто используете средство проверки типов (mypy,pyright, pytype, PyCharm,...), а не разрабатываете его, вам вообще не нужно взаимодействовать с репозиторием typeshed: копия стандартной библиотеки, часть typeshed поставляется в комплекте с проверкой типов. А заглушки типов для сторонних пакетов и модулей, которые вы используете, можно установить из PyPI. Например, если вы используете html5lib и requests , вы можете установить заглушки типов, используя

$ pip install types-html5lib types-requests

Эти пакеты PyPI соответствуют PEP 561 и автоматически выпускаются (до одного раза в день) с помощью внутренних механизмов.

Средства проверки типов должны иметь возможность использовать эти пакеты-заглушки после установки. Более подробную информацию смотрите в документации по вашей программе проверки типов.

Управление версиями пакетов для сторонних заглушек

Номера версий сторонних пакетов-заглушек состоят как минимум из четырех частей. Все части версии-заглушки, за исключением последней части, соответствуют версии пакета среды выполнения, для которого создается заглушка. Например, если пакет types-foo имеет версию 1.2.0.20240309 , это гарантирует, что пакет types-foo содержит заглушки, нацеленные на foo==1.2.* и проверенные на соответствие последней версии foo , соответствующей этому спецификатору. В этом примере последний элемент номера версии (20240309) указывает, что пакет-заглушка был отправлен 9 марта 2024 года.

В typesh мы стараемся свести критические изменения к минимуму. Однако из-за природы заглушек любое изменение версии может привести к изменениям, из-за которых ваш код может не пройти проверку типа.

Существует несколько стратегий, позволяющих указать версию используемого вами пакета заглушек, каждая из которых имеет свои недостатки:

1. Используйте те же границы, которые вы используете для стабируемого пакета. Например, если вы используете requests>=2.30.0,<2.32 , вы можете использовать types-requests>=2.30.0,<2.32 . Это гарантирует совместимость заглушек с используемым вами пакетом, но несет небольшой риск нарушения проверки типов из-за изменений в заглушках.

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

2. Прикрепите заглушки к заведомо исправной версии и время от времени обновляйте их (либо вручную, либо с помощью такого инструмента, как dependabot или renovate).

   Например, если вы используете types-requests==2.31.0.1 , вы можете быть уверены, что обновление зависимостей не нарушит проверку типов. Однако вы упустите улучшения в заглушках, которые потенциально могут улучшить проверку типов, пока вы не обновите вывод. Эта стратегия также сопряжена с риском того, что используемые вами заглушки могут стать несовместимыми с заглушаемым пакетом.

3. Не прикрепляйте заглушки. Это вариант, который требует от вас наименьшего количества усилий, когда дело доходит до обновления контактов версии, и имеет то преимущество, что вы автоматически получаете улучшенные заглушки при каждом выпуске новой версии пакета заглушек. Однако существует риск того, что заглушки станут несовместимыми с заглушаемым пакетом.

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

Вы также можете переключаться между различными стратегиями по мере необходимости. Например, вы можете по умолчанию использовать стратегию (1), но вернуться к стратегии (2), когда возникает проблема, которую нелегко устранить.

Пакет _typeshed

typeshed включает пакет _typeshed как часть стандартной библиотеки. Этот пакет и его подмодули содержат типы утилит, но недоступны во время выполнения. Дополнительные сведения о том, как использовать этот пакет, см. в каталоге stdlib/_typeshed .

Обсуждение

Если вы столкнулись с поведением средства проверки типов, которое предполагает, что заглушки типов для данной библиотеки неверны или неполны, мы хотим услышать ваше мнение!

Нашим основным форумом для обсуждения является трекер проблем проекта GitHub. Это подходящее место, чтобы начать обсуждение любого из вышеперечисленных или большинства других тем, касающихся проекта.

Если у вас есть общие вопросы о наборе текста на Python или вам нужен обзор ваших аннотаций типов или заглушек за пределами typeshed, зайдите на наш дискуссионный форум. Для менее формального обсуждения попробуйте чат-чат на gitter.im. Некоторые сопровождающие, работающие с типом, присутствуют почти всегда; не стесняйтесь найти нас там, и мы будем рады пообщаться. Существенная техническая дискуссия будет направлена ​​на систему отслеживания проблем.