### 如何生成或手动创建 Python 的 `.pyi` 类型提示文件 `.pyi` 文件是一种特殊的类型存根文件，主要用于提供静态类型的元数据支持。它允许开发者为动态编写的代码添加类型注解而不改变实际运行逻辑。以下是关于如何生成或手动创建 `.pyi` 文件的相关说明。 #### 手动生成 `.pyi` 文件 手动生成 `.pyi` 文件的过程涉及提取现有模块中的公共接口，并为其添加类型注解。以下是一个简单的例子： 假设有一个 `example.py` 文件，其内容如下： ```python def add(a, b): return a + b class Calculator: def multiply(self, x, y): return x * y ``` 对应的手动创建的 `example.pyi` 文件可能看起来像这样： ```python def add(a: int, b: int) -> int: ... class Calculator: def multiply(self, x: float, y: float) -> float: ... ``` 注意这里的省略号 (`...`) 表示该函数的具体实现被忽略，仅保留类型信息[^1]。 #### 自动生成 `.pyi` 文件 对于大型项目来说，手动编写 `.pyi` 文件可能会非常耗时且容易出错。因此，可以借助工具自动生成这些文件。常用的工具有以下几个： 1. **stubgen**: 这是来自 mypy 工具的一个子命令，能够扫描指定的源码目录并生成对应的 `.pyi` 存根文件。 ```bash stubgen example.py ``` 上述命令会基于 `example.py` 创建一个初始版本的 `example.pyi` 文件[^2]。 2. **Pyright**: Pyright 是微软推出的一款强大的类型检查器，也提供了类似的存根生成功能。通过配置合适的选项，它可以自动推断某些未标注的类型并将它们导出到 `.pyi` 文件中。 3. **Jedi**: Jedi 是另一个流行的 Python 自动补全库，虽然它的主要用途不是生成 `.pyi` 文件，但它内部实现了复杂的 AST 解析功能，理论上也可以扩展用来辅助完成这项任务。 无论采用哪种方式，最终都需要人工审查生成的结果以确保准确性，因为自动化过程难免存在局限性和误判情况。 #### 使用场景与注意事项 - `.pyi` 文件通常只应暴露给外部使用的 API 接口部分；私有成员一般不需要包含其中。 - 如果同一个包里既有实现又有相应的存根，则需特别小心命名冲突问题——推荐做法是在独立子目录下存放所有的 `.pyi` 文件以便区分管理。 ```python # 正确示范：单独放置于 types/ 下面 types/example.pyi ```