Python pyi文件

### Python 的 `.pyi` 文件用途 `.pyi` 文件是专门设计来提供 Python 代码静态类型信息的特殊文件[^2]。这类文件也称为存根文件（stub files）或类型提示文件（type hint files），主要用于辅助类型检查和静态分析工具。 #### 存根文件的作用 通过引入 `.pyi` 文件，开发者可以在不修改原始源代码的情况下为现有模块添加类型注解。这有助于： - 提高 IDE 或编辑器内联帮助的质量 - 改善自动补全功能的表现 - 增强错误检测能力，在编译期而非运行时发现潜在问题 - 方便其他开发人员理解函数签名及其预期输入输出参数 #### 类型提示语法 对于新项目而言，推荐直接在 `.py` 源文件中使用 PEP 484 定义的标准类型标注语法；而对于遗留系统，则可以通过创建对应的 `.pyi` 存根文件来进行补充说明[^4]。 以下是定义一个简单类 `Point` 并为其编写配套 `.pyi` 文件的例子： ```python # point.py class Point(object): def __init__(self, x=0.0, y=0.0): self.x = float(x) self.y = float(y) def distance_from_origin(self) -> float: import math return math.hypot(self.x, self.y) # point.pyi from typing import Tuple class Point: x: float y: float def __init__(self, x: float = ..., y: float = ...) -> None: ... def distance_from_origin(self) -> float: ... @staticmethod def from_tuple(coordinates: Tuple[float, float]) -> 'Point': ... ``` 在这个例子中，虽然实际实现位于 `point.py` 中，但是为了支持更好的类型检查体验，额外提供了更详细的接口描述于 `point.pyi` 文件里。注意这里还增加了一个不存在于原版中的静态方法声明作为示例展示如何扩展 API 文档而无需改变原有逻辑。