每天认识一个github项目：typeshed项目介绍

你是否好奇过，为什么在 IDE 中敲下 requests.get 时，能立刻看到完整的参数提示？又或者 mypy 是如何在不运行代码的情况下发现类型错误的？答案就是 typeshed。这个由 Python 官方维护的“类型存根仓库”为 Python 标准库和大量第三方库提供了准确的类型标注。它让类型检查、自动补全、重构变得更加可靠，是每位 Python 开发者都值得了解的基础设施。

项目概览

typeshed 是一个专门存放 Python 类型存根（type stubs）的仓库。它不属于某个具体的运行时库，而是为 Python 标准库、内置对象以及第三方包提供外部的类型注解文件。这些 .pyi 文件描述了一个函数、类或模块的公开类型接口，类型检查器（如 mypy、Pyright、PyCharm）可以据此对代码进行静态分析，从而在不运行程序的情况下发现潜在错误。

项目标签

该仓库在 GitHub 上使用的核心标签如下：

• • python
• • stub
• • types
• • typing

这些标签清楚地表达了 typeshed 的定位：面向 Python 的类型存根集合，服务于类型标注与静态类型检查生态。

最新发布

typeshed 本身不采用传统语义化版本号，而是以日期作为版本标识。每次合并到主分支的存根更新，都会通过内部发布机制同步到 PyPI 的 types-* 包中。以下是最新的版本信息：

项目文档预览

核心特性

特性 1：标准库与内建对象类型存根全覆盖

typeshed 包含 Python 标准库和内置对象的完整类型注解。无论是最基础的 builtins.pyi、typing.pyi，还是 os、json、pathlib 等标准库模块，都有对应的 .pyi 文件。类型检查器会优先读取这些存根，从而准确推断出函数参数、返回值以及异常类型。

这意味着，即使你不给代码添加任何类型标注，类型检查器依然能基于标准库存根发现明显的类型错误。

特性 2：第三方存根自动发布与版本同步

typeshed 不只是面向标准库，它还维护了大量第三方库的存根。这些存根以 types-<package-name> 的形式发布到 PyPI，例如 types-requests、types-html5lib、types-PyYAML。存根包的版本号设计非常巧妙，例如 types-requests==2.31.0.20240309：

• • 2.31.0 表示对应的运行时包 requests 的版本范围；
• • 20240309 表示存根包的发布时间。

这种机制保证了存根与运行时库的版本能够尽量同步演进，同时让用户可以精确控制存根版本。

特性 3：与主流类型检查器深度集成

mypy、Pyright、PyCharm 等工具都内置或默认使用 typeshed 的标准库存根。typeshed 提供的数据可以广泛应用于：

• • 静态类型检查；
• • 类型推断；
• • 自动补全；
• • 重构辅助；
• • IDE 智能提示。

由于 typeshed 遵循 Python typing 规范，它已经成为 Python 类型生态中事实上的标准数据源。

演示与效果

媒体类型：命令行演示 / 代码示例

typeshed 本身没有图形界面，因此我们通过类型检查器的输出来展示它的作用。下面是一个简单的 mypy 示例：

# demo.py
def add_one(x: int) -> int:
    return x + 1

add_one("hello")  # 传入字符串，类型不兼容

运行 mypy demo.py 后，mypy 会输出：

demo.py:5: error: Argument 1 to "add_one" has incompatible type "str"; expected "int"
Found 1 error in 1 file (checked 1 source file)

这个报错信息实际上是由 typeshed 中 int、str 的类型定义所驱动的。正是因为 typeshed 提供了精确的存根，mypy 才能判断出 str 不能传给 int 参数。

在线体验：无在线演示地址，可参考 Python 官方 typing 文档：https://typing.readthedocs.io/en/latest/

技术栈

架构设计

typeshed 的仓库结构大致如下：

typeshed/
├── stdlib/              # 标准库与内置对象存根
│   ├── builtins.pyi
│   ├── os/
│   ├── json/
│   ├── pathlib.pyi
│   ├── typing.pyi
│   └── _typeshed/       # 内部工具类型，仅用于类型检查
├── stubs/               # 第三方库存根
│   ├── requests/
│   ├── html5lib/
│   ├── PyYAML/
│   └── ...
├── tests/               # 存根正确性测试
├── CONTRIBUTING.md      # 贡献指南
└── README.md

这种目录化、模块化的组织方式，使得 typeshed 可以针对不同第三方包独立维护和发布存根。

快速开始

1. 环境准备

如果只是作为普通用户使用类型检查器，你不需要手动安装 typeshed，因为 mypy、Pyright、PyCharm 已经内置了 typeshed 的标准库部分。你需要的是：

• • Python 3.10+（推荐 3.12 或 3.13）
• • pip
• • 一个类型检查器，例如 mypy

如果你希望为 typeshed 贡献存根，还需要：

• • Git
• • Python 3.10+ 环境
• • virtualenv 或 venv

2. 安装类型检查器

推荐使用 mypy 作为第一个类型检查器，它安装简单、使用直观。

python -m venv .venv
source .venv/bin/activate      # Windows 下使用 .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install mypy

3. 编写并检查你的第一个文件

创建一个 example.py：

from pathlib import Path

def read_first_line(path: Path) -> str:
    return path.read_text().splitlines()[0]

print(read_first_line(Path(__file__)))

运行：

mypy example.py

此时 mypy 应该没有任何报错。下面故意传入一个错误类型：

print(read_first_line("example.py"))  # 错误：应传入 Path，而不是 str

再次运行：

mypy example.py

你会看到类似输出：

example.py:7: error: Argument 1 to "read_first_line" has incompatible type "str"; expected "Path"
Found 1 error in 1 file (checked 1 source file)

这正是 typeshed 中 pathlib.Path 的类型定义在起作用。

4. 安装第三方库类型存根

如果你的项目使用 requests、html5lib、PyYAML 等第三方库，可以安装对应的 types-* 包：

python -m pip install types-requests types-html5lib types-PyYAML

例如，安装 types-requests 后，以下代码可以通过 mypy 检查：

import requests

def fetch_json(url: str) -> dict:
    response = requests.get(url)
    response.raise_for_status()
    return response.json()

如果没有安装 types-requests，mypy 可能会因为缺少类型信息而报错或跳过检查。

5. 为 typeshed 贡献存根

如果你想参与 typeshed 的贡献，可以按以下步骤操作：

git clone https://github.com/python/typeshed.git
cd typeshed
python -m venv .venv
source .venv/bin/activate      # Windows 下使用 .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements-tests.txt

运行全部测试：

pytest tests/

修改 stdlib/ 或 stubs/ 目录下的 .pyi 文件后，请务必运行测试并参考 CONTRIBUTING.md 中的贡献规范。

6. 进阶用法

• • 指定 Python 版本进行检查：

  mypy --python-version 3.12 example.py

• • 使用 _typeshed 包中的工具类型：

  # 在存根文件中使用
  from _typeshed import StrPath
  
  def load(path: StrPath) -> str: ...

  _typeshed 是 typeshed 内部提供的一个特殊包，包含许多工具类型，但它不可以在运行时导入，只服务于类型检查场景。

项目分析

热度指标

typeshed 的星标/分支比约为 2.47，说明平均每个 fork 会带来约 2.5 个 star，项目具有较高的社区认可度。同时，项目最近更新日期为 2026-08-15，即在报告生成前一天仍有提交，维护非常活跃。

推荐理由

1. 1. 生态核心地位：typeshed 是 Python 类型检查生态中的基础设施，mypy、Pyright、PyCharm 等主流工具都依赖它。
2. 2. 技术栈专业：项目使用 Python 语言开发，专注于 .pyi 类型存根，是学习 Python 类型标注的最佳材料。
3. 3. 社区认可度高：获得 5108 个星标和 2072 个分支，说明其在开发者社区中具有广泛影响力。
4. 4. 持续维护：项目从 2015 年创建至今，保持高频更新，并且紧跟 Python 3.10-3.14 的发展。
5. 5. 文档完整：提供了详细的 README、CONTRIBUTING 文档，并链接到 Python typing 规范文档，降低了参与门槛。

使用建议

• • 普通 Python 开发者：将 typeshed 视为“类型检查的地基”，配合 mypy 或 PyCharm 使用，可以让代码在运行前发现大量隐藏错误。
• • 第三方库作者：为自己的库编写 .pyi 存根文件，或参考 typeshed 中的优秀存根实现，提升库的类型可描述性。
• • 工具链开发者：如果你的项目涉及代码分析、自动补全或编译期优化，可以深入研究 typeshed 的数据结构和发布机制。
• • 学习者：阅读 stdlib/builtins.pyi 和 stdlib/typing.pyi，可以快速理解 Python 类型系统的核心概念。

README（中文翻译）

以下内容是对 typeshed 官方 README 的完整中文翻译。

typeshed

关于

typeshed 包含 Python 标准库和 Python 内置对象的外部类型注解，以及由非相关项目的外部人员贡献的第三方包类型注解。

这些数据可以用于静态分析、类型检查、类型推断和自动补全等场景。

关于如何使用 typeshed，请阅读下文。贡献者信息请参阅 CONTRIBUTING.md。请在提交拉取请求之前阅读该文件；不要向存根所针对的项目报告注解问题，而应在此处向 typeshed 报告。

关于存根文件、typeshed 以及 Python typing 系统的更多文档，请访问 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 包遵循 typing 规范标准，并由 typeshed 内部机制 自动发布（最多每天一次）。

安装这些存根包后，类型检查器应该能够直接使用它们。更多细节请参阅你的类型检查器的文档。

第三方存根的包版本

第三方存根包的版本号至少由四个部分组成。存根版本的所有部分（最后一部分除外）都对应于被存根运行时包的版本。例如，如果 types-foo 包的版本号为 1.2.0.20240309，这保证 types-foo 包包含针对 foo==1.2.* 的存根，并与匹配该规范的最新版 foo 进行过测试。在这个例子中，版本号的最后一个元素（20240309）表示该存根包于 2024 年 3 月 9 日推送。

在 typeshed，我们尽量减少破坏性变更。然而，由于存根的特性，任何版本提升都可能引入导致你的代码无法通过类型检查的更改。

有几种策略可以用来指定你正在使用的存根包版本，每种策略都有各自的权衡：

1. 1. 使用与被存根包相同的版本边界。例如，如果你使用 requests>=2.30.0,<2.32，你可以使用 types-requests>=2.30.0,<2.32。这确保存根与你使用的包兼容，但它有因存根更改而破坏类型检查的小风险。

   这种策略的另一个风险是，存根通常会滞后于被存根的包。你可能希望将被存根的包强制为某个最低版本，因为它修复了关键错误；但如果相应更新的存根尚未发布，你的类型检查结果可能不完全准确。

2. 2. 将存根固定到一个已知的良好版本，并定期更新该固定版本。你可以手动更新，也可以使用 Dependabot 或 Renovate 等工具。

   例如，如果你使用 types-requests==2.31.0.1，你可以确信升级依赖不会破坏类型检查。但是，在更新固定版本之前，你会错过存根中可能改进类型检查的功能。这种策略也有风险：你正在使用的存根可能会与被存根的包变得不兼容。

3. 3. 不固定存根版本。这是你更新版本固定所需工作量最少的选项，并且具有每次存根包发布新版本时自动受益于改进存根的优势。然而，它存在存根与被存根的包变得不兼容的风险。

   例如，如果一个包发布了新的主版本，那么在你更新被存根的包之前，存根可能已经被更新以反映运行时包的新版本。

你也可以根据需要在这些不同策略间切换。例如，你可以默认使用策略（1），当出现无法轻松解决的问题时，再回退到策略（2）。

_typeshed 包

typeshed 将 _typeshed 包作为标准库的一部分包含在内。该包及其子模块包含工具类型，但运行时不可用。有关如何使用此包的更多信息，请参阅 stdlib/_typeshed 目录。

讨论

如果你遇到了类型检查器的行为表明某个库的类型存根不正确或不完整，我们希望听到你的反馈！

我们的主要讨论论坛是项目的 GitHub issue 追踪器。这是开始讨论上述任何主题或与项目相关的大多数其他主题的正确场所。

如果你有关于 Python typing 的一般性问题，或者需要审查超出 typeshed 范围之外的类型注解或存根，请前往我们的讨论论坛。想要更非正式的讨论，请尝试 gitter.im 上的 typing 聊天室。一些 typeshed 维护者几乎总是在线；欢迎在那里找到我们，我们很乐意聊天。实质性的技术讨论将被引导到 issue 追踪器。

结语：typeshed 虽然不像一个应用框架那样引人注目，但它默默支撑着 Python 类型检查、IDE 提示和代码补全的整个生态。理解并使用 typeshed，会让你离“专业 Python 开发”更近一步。

**本文档根据python/typeshed项目官方仓库内容整理，只在提供清晰的项目介绍和试用指引，所有工具的使用者应当遵守当地的法律法规，请勿用于非法用途！关注我，每天8点带你解锁一个github开源项目！