typeshed
1.0.0
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，并通过 typeshed 内部机制自动发布（最多每天一次）。
安装后类型检查器应该能够使用这些存根包。有关更多详细信息，请参阅类型检查器的文档。
第三方存根包的版本号至少由四部分组成。存根版本的所有部分（除了最后一部分）都对应于被存根的运行时包的版本。例如，如果types-foo包的版本为1.2.0.20240309 ，则这保证types-foo包包含针对foo==1.2.*存根，并针对与该说明符匹配的最新版本foo进行测试。在此示例中，版本号的最后一个元素 (20240309) 表示存根包于 2024 年 3 月 9 日推送。
在 typeshed 中，我们尝试将破坏性更改保持在最低限度。但是，由于存根的性质，任何版本更新都可能会引入更改，从而可能使您的代码无法进行类型检查。
有多种策略可用于指定您正在使用的存根包的版本，每种策略都有自己的权衡：
使用与要存根的包相同的边界。例如，如果您使用requests>=2.30.0,<2.32 ，则可以使用types-requests>=2.30.0,<2.32 。这确保了存根与您正在使用的包兼容，但由于存根的更改，它会带来破坏类型检查的小风险。
此策略的另一个风险是存根通常落后于被存根的包。您可能希望强制将包存根到某个最低版本，因为它修复了一个关键错误，但如果相应更新的存根尚未发布，您的类型检查结果可能不完全准确。
将存根固定到已知的良好版本，并不时更新该固定（手动或使用 dependentabot 或 renovate 等工具）。
例如，如果您使用types-requests==2.31.0.1 ，您可以确信升级依赖项不会破坏类型检查。但是，在更新引脚之前，您将错过存根中可能会改进类型检查的改进。此策略还存在以下风险：您正在使用的存根可能与所存根的包不兼容。
不要固定存根。该选项在更新版本引脚时要求您做的工作最少，并且具有以下优点：每当发布新版本的存根包时，您将自动受益于改进的存根。然而，它存在存根与被存根的包不兼容的风险。
例如，如果发布了包的新主要版本，则在更新要存根的包之前，存根可能会更新以反映运行时包的新版本。
您还可以根据需要在不同策略之间切换。例如，您可以默认采用策略 (1)，但当出现无法轻易解决的问题时，您可以回退到策略 (2)。
_typeshed包typeshed 包含一个包_typeshed作为标准库的一部分。该包及其子模块包含实用程序类型，但在运行时不可用。有关如何使用此包的更多信息，请参阅stdlib/_typeshed目录。
如果您在类型检查器中遇到表明给定库的类型存根不正确或不完整的行为，我们希望收到您的来信！
我们的主要讨论论坛是该项目的 GitHub 问题跟踪器。这是开始讨论上述任何主题或与该项目相关的大多数其他主题的正确位置。
如果您对使用 Python 键入有一般性问题，或者您需要在 typeshed 之外查看类型注释或存根，请访问我们的讨论论坛。对于不太正式的讨论，请尝试 gitter.im 上的打字聊天室。一些 typeshed 维护者几乎总是在场；请随时在那里找到我们，我们很乐意与您聊天。实质性技术讨论将针对问题跟踪器。
