typeshed
关于
Typeshed 包含 Python 标准库和 Python 内置函数的外部类型注解， 以及由这些项目外部人员贡献的第三方包。
这些数据可用于静态分析、类型检查、类型推断 和自动补全等场景。
有关如何使用 typeshed 的信息，请阅读下文。 贡献者 相关信息可在 CONTRIBUTING.md 中找到。 请在提交拉取请求前阅读 该文件；不要向存根所对应的项目报告注解问题，而是在此向 typeshed 报告。
有关存根文件、typeshed 以及 Python 类型系统的更多文档， 也可在 https://typing.readthedocs.io/en/latest/ 找到。
Typeshed 支持 Python 3.10 到 3.14 版本。
使用
如果你只是使用类型检查器（例如 mypy、
pyright 或 PyCharm 内置的类型
检查器），而不是
开发它，则完全不需要与 typeshed 仓库交互：
类型检查器中捆绑了 typeshed 标准库部分的副本。
你正在使用的第三方包和模块的类型存根
可以从 PyPI 安装。例如，如果你正在使用 html5lib 和 requests，
你可以使用以下命令安装类型存根
$ pip install types-html5lib types-requests这些 PyPI 包遵循 类型规范标准 ，并由 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。这确保了存根与 您正在使用的包兼容，但由于存根中的变更，存在 破坏类型检查的微小风险。
该策略的另一个风险在于，存根（stubs）往往落后于 被存根化的包。你可能希望将被存根化的包强制固定到某个最低版本， 因为它修复了一个关键 bug，但如果相应更新的存根尚未发布， 你的类型检查结果可能不会完全准确。 2. 将存根固定到已知良好的版本，并时不时更新该固定版本 （手动更新，或使用 dependabot 或 renovate 等工具）。
例如，如果你使用 types-requests==2.31.0.1，你可以确信
升级依赖项不会破坏类型检查。然而，在
你更新固定版本之前，你将错过存根中可能改进类型
检查的改进。该策略也存在风险，即
你正在使用的存根可能与被存根化的包不兼容。
3. 不要固定存根。这是在你更新版本固定时
要求最少工作量的选项，并且具有优势，即每当
存根包发布新版本时，你都会自动受益于改进的存根。然而，它存在
存根与被存根化的包不兼容的风险。
例如，如果该包发布了新的主要版本， 存根可能会在更新被存根化的包之前， 被更新以反映运行时包的新版本。
你也可以根据需要在不同的策略之间切换。例如， 你可以默认使用策略 (1)，但当出现难以轻松修复的问题时， 回退到策略 (2)。
_typeshed 包
typeshed 包含标准库的一部分，即 _typeshed 包。
该包及其子模块包含实用类型，但在运行时不可用。有关如何使用此包的更多信息，
请参阅 stdlib/_typeshed 目录。
讨论
如果你在类型检查器中遇到了表明某个库的类型 存根不正确或不完整的行为， 我们想听听你的意见！
我们主要的讨论论坛是该项目的 GitHub issue tracker。 这是开始讨论上述任何内容或 大多数其他与项目相关话题的正确场所。
如果你有关于 Python 类型注解的一般性问题，或者你需要 在 typeshed 之外审查你的类型注解或存根，请前往 我们的讨论论坛。 对于不太正式的讨论，请尝试 typing 聊天室 gitter.im。 一些 typeshed 维护者 几乎总是在线；请随时在那里找到我们，我们很乐意 聊天。 实质性的技术讨论将被引导至 issue tracker。