Python .pyi类型存根文件教程：最接近“头文件”的现代实践

一、什么是 .pyi：从“头文件”思维理解接口契约

.pyi（Python Interface）是 Python 官方在 PEP 484 与 PEP 561 中标准化的类型存根文件（Stub File）。它的核心定义极其直观：只包含类型签名、属性与接口定义，不包含任何具体的执行逻辑与函数体代码。

在传统 C/C++ 工程中，开发者通过 .h 或 .hpp 文件声明函数原型、结构体定义与公共宏，而由 .c 或 .cpp 提供真正的机器码实现。调用方代码在预处理与编译阶段只需包含头文件，编译器即可验证参数类型与符号有效性。

现代 Python 的 .pyi 完整延续了这一思想，但运作层面上有着根本性的环境解耦：

• 零运行时开销（Runtime-Ignored）：当 Python 解释器（CPython）执行代码时，.pyi 文件被完全跳过。Python 虚拟机只认 .py 脚本或 .so / .pyd 扩展，存根文件不参与内存加载，因此不会引发任何性能损失或模块启动延迟。
• 静态期强约束（Static-Only）：IDE 语言服务器（如 VS Code 的 Pylance/Pyright、PyCharm）和静态检查工具（Mypy）在做代码补全、跳传引用与全量检查时，会优先抓取 .pyi。存根文件充当了面向开发工具的绝对真实契约。

二、四大核心场景：为什么不直接在 .py 里写类型？

Python 3.5 以后允许在 .py 源码中直接编写类型注解（如 def add(x: int) -> int: ...），既然如此，为什么还要单独分理出 .pyi 存根？以下四类工程场景构成了 .pyi 不可替代的刚性需求：

1. C/C++/Rust 编译型二进制扩展（.so / .pyd）

当使用 Cython、PyO3（Rust）、pybind11 或原生 C API 编写高性能底层模块时，编译输出的是纯二进制动态链接库。动态库在磁盘上不包含任何 Python AST 抽象语法树信息。若没有 .pyi，IDE 面对导入的模块只能将其标记为 Any，无法提供任何自动补全与静态排错。通过在同级目录放置 module.pyi，即可为黑盒二进制扩展赋予完整的类型支持。

2. 消除极速启动场景下的 typing 运行时损耗

在 CLI 命令行工具、微服务冷启动或高频派生进程（Fork-heavy）系统中，import typing 以及求值复杂的类型表达式（如深度嵌套的泛型、自定义 Protocol、Pydantic 模式等）会消耗毫秒级的启动时间和数兆字节的内存。将类型定义外置到 .pyi 后，.py 源码保持无注解的纯粹运行态，既保障开发期类型安全，又获得绝对纯净的原生执行速度。

3. 隔离庞大遗留代码库或第三方无类型库

对于体量庞大的既有系统，直接在数万行历史代码中插入类型注解往往存在极高侵入性风险（如引发循环引用、动态反射异常）。编写外置 .pyi 可以实现“非侵入式打补丁”，业务源码一行不改，外部调用者已能享受严格的类型检查。官方 Typeshed 社区库即是这种方式的代表。

4. 表达动态元编程的静态契约

在重度依赖 __getattr__、动态代理或装饰器重写签名的框架中，运行时的签名与静态期期望完全不一致。在 .py 中很难使用常规注解满足类型推导，而在 .pyi 中可以直接显式写出重载签名（@overload），呈现清晰无歧义的公共 API。

三、.pyi 核心语法规约与关键陷阱

编写 .pyi 遵循 Python 语法子集，但在细节上有几项必须严格遵守的特殊规约。

1. 省略体（Ellipsis ...）取代函数体

存根中不允许出现具体实现逻辑，函数体或属性定义统一使用三个英文句点 ...（即 Python 单例对象 Ellipsis），避免使用 pass。

2. 默认参数值应当抽象化为 ...

在 .pyi 中，默认参数的目的仅是告知类型检查器“该参数为可选参数”，不需要声明具体的运行时计算值。除非是简单的字面量（如 0, None），复杂默认值建议一律写为 ...：

# 推荐规范：明确该参数可选，且默认值细节由底层决定
def connect(host: str, port: int = 8080, timeout: float | None = ...) -> Connection: ...

3. 模块导入与重导出（Re-export）规则（重大陷阱！）

这是初学者最容易踩雷的规则差异。在普通的 .py 文件中，只要执行了 from math import sin，sin 就会成为模块命名空间的成员被外界访问。但在 .pyi 存根文件中，PEP 484 规定：所有未显式重导出的导入均被视为存根内部私有辅助符号。

如果希望在 .pyi 中导出导入的类型供外部模块使用，必须采用以下两种方式之一：

• 别名自绑定语法：from math import sin as sin 或 import os as os。多出的 as sin 明确向检查器表明“该符号是对外公开的 API”。
• 定义 __all__ 列表：在存根中声明 __all__ = ["sin", "cos"]。

4. 代码对照实战：.py 与 .pyi 对照

观察同一个数据处理服务在实现端与存根端的代码对照：

# service.py 运行时逻辑
class DataService:
    def __init__(self, endpoint, retry=3):
        self._endpoint = endpoint
        self._retry = retry
        self._cache = {}

    def fetch(self, key, fallback=None):
        if key in self._cache:
            return self._cache[key]
        # 执行实际 HTTP 或底层调用
        res = self._do_request(key)
        return res if res else fallback

    def _do_request(self, key):
        ...

# service.pyi 纯净类型契约
from typing import TypeVar, overload

_T = TypeVar("_T")

class DataService:
    def __init__(self, endpoint: str, retry: int = ...) -> None: ...
    
    @overload
    def fetch(self, key: str) -> dict[str, str] | None: ...
    @overload
    def fetch(self, key: str, fallback: _T) -> dict[str, str] | _T: ...

注意存根的精妙之处：私有方法 _do_request 和内部状态 _cache 被安全地完全隐藏，对外展示更严密的 @overload 返回值推导。

四、全流程实战：编写、生成与对齐校验

若手工为成百上千个模块逐行手写 .pyi，成本极高且容易产生语法失误。标准的工业级实践应当遵循“自动脚手架 -> 精修契约 -> CI 反射校验”的三阶闭环。

# 为指定 Python 源码包生成存根并输出至当前目录
$ stubgen -p my_package -o .

# 为编译好的 C/Rust 二进制模块生成存根
$ stubgen -m my_native_extension -o .

# 执行双向反射一致性测试
$ stubtest my_package

# 示例检测到漂移时的报错输出：
error: my_package.DataService.fetch in stub has parameter "key" but runtime has "item_key"
error: my_package.utils.legacy_helper is present in stub but missing at runtime

五、PEP 561 规范：打包分发与查找优先级

当你将写好的模块打包上传至 PyPI 或在公司内部分发时，如何让下游调用方的 Mypy 与 Pylance 准确识别你的类型存根？这依赖 PEP 561 的定位机制。

1. py.typed 标记文件

若你的包属于源码同级携带存根（Inline/Sibling Stubs），必须在模块顶级目录中创建一个名为 py.typed 的空文件。同时在构建配置中确保该文件不被忽略：

# pyproject.toml 配置示例 (以 Hatch / Setuptools 为例)
[tool.setuptools.package-data]
my_package = ["*.pyi", "py.typed"]

缺少 py.typed，调用方的类型检查器会默认认定该第三方包“不支持类型提示”，从而把所有导入强制降级为 Any 并发出找不到类型注解的警报。

2. 类型检查器的四级查找阶梯

如上方图 3 所示，当调用方执行 import foo 时，类型检查器严格按照以下顺序进行符号解析：

1. 独立存根包（Stub-only packages）：优先查找安装在环境中的 foo-stubs 或 types-foo。这种设计允许社区在不打扰原包作者的前提下更新类型。
2. 包内同级存根（Sibling .pyi）：若源码包中同时存在 foo/bar.py 与 foo/bar.pyi，检查器会完全采用 .pyi 的定义，直接无视 .py 中的任何类型注释。
3. 携带 py.typed 的内联源码：当不存在 .pyi 时，检查器直接提取 .py 内部的函数签名与注解。
4. 内置 Typeshed 库兜底：最后回退到类型检查器随身携带的官方与第三方存根库。

六、工程选型：内联注解与独立存根的权衡

.pyi 并非取代内联类型注解的万能药，而是一种面向特定边界的高阶工程手段。在决定是否采用 .pyi 时，可参考图 4 与下述量化判定矩阵：

七、总结与生产速查

Python 的 .pyi 存根文件绝非旧时代头文件的简单复刻，而是针对现代动态语言在大型软件工程、跨语言混合编程及严格类型检查环境下的演进答案。它把“写给机器执行的代码”与“写给人及工具推导的契约”做出了优雅解耦。

掌握 .pyi，核心要领可归纳为三句口诀：

• 存根归静态，运行归虚拟机：.pyi 不占运行时一分一秒，所有代码体皆为 ...。
• 重导出必显式，导入不可想当然：未用 as 或 __all__ 声明的导入对外不可见。
• 上线必跑 stubtest：杜绝人工维护不同步，将接口漂移拦截在代码提交之前。