typeshed：Python 类型生态的底层支撑
Python 从动态类型走向静态类型检查，typeshed 是这条路径上的关键基础设施。这个项目由 Python 官方维护，汇集了标准库、内置函数以及大量第三方包的类型存根。目前它在 GitHub 上已获得 5,070 个 Star。
它的核心作用
简单来说，typeshed 存的是那些没有自带类型注解的代码的 .pyi 文件。当你用 mypy、pyright 或 PyCharm 的类型检查器时，这些工具会调用 typeshed 中的存根，来判断你的代码类型是否正确。
它的覆盖范围包括：
- Python 标准库和内置函数
- 第三方包的社区贡献存根
- 专供类型检查使用的 _typeshed 工具包
这些数据支撑着静态分析、类型推断和代码补全。它的价值主要体现在成为整个 Python 类型生态的公共依赖，单独使用它的情况很少。
普通开发者需要做什么
答案通常是：什么都不用做。
如果你只是使用类型检查器，标准库部分的 typeshed 已经内置在工具里。第三方库如果需要类型存根，直接从 PyPI 安装对应的 types- 包即可。比如用了 requests 和 html5lib，可以这样装：
pip install types-requests types-html5lib
typeshed 官方每天都会通过自动化工具发布更新，所以这些存根包基本能跟上上游库的变化。安装后，类型检查器会自动识别并使用它们。
版本号里的门道
第三方存根的版本号至少有四段。前三段对应被存根的实际库版本，最后一段是发布日期。例如 types-foo==1.2.0.20240309，表示这个存根针对 foo 的 1.2.* 版本，发布于 2024 年 3 月 9 日。
这种设计让版本选择变得有讲究。你可以：
- 跟着运行时包版本走，保持边界一致
- 固定到某个已知可用的版本，定期手动更新
- 完全不固定，自动接受最新发布
三种策略各有利弊。方案一最自然，但存根更新可能略慢于你升级依赖，导致短暂的类型检查偏差。方案二最稳，适合对构建稳定性要求高的项目，但会错过改进。方案三最省事，却可能在库大版本升级时引入不兼容的类型报错。实际项目中，可以根据阶段切换策略。
谁该关注它
日常写 Python 的人可能永远不会打开 typeshed 仓库，但它每天都在影响你的开发体验。从 IDE 的补全提示到 CI 里的类型检查，底层都有它的身影。
如果你正在维护一个 Python 库，考虑为它贡献类型存根是回馈社区的好方式。typeshed 接受外部贡献，且有明确的协作规范。对于希望代码更健壮的项目来说，这套机制已经是现代 Python 开发里不可缺少的一部分。
