"桩代码"（stub）是**假实现、占位符**，不是真正的功能代码。
## 本质
| 类型 | 作用 | 例子 |
|------|------|------|
| **真实实现** | 实际运行的逻辑 | C 语言写的 `enumerate` 迭代器 |
| **桩代码（stub）** | 给类型检查工具/IDE 看的"说明书" | `.pyi` 文件里的假函数 |
## enumerate 的真实 vs 桩代码
```
Python 源码结构：
Lib/
├── enum.py ← 真实实现（运行时执行）
└── typeshed/
└── stdlib/
└── builtins.pyi ← 桩代码（给 mypy/IDE 看）
```
**真实实现**（C 层，简化示意）：
```python
# 这是 C 写的，实际在 python.exe 里
class enumerate:
def __init__(self, iterable, start=0):
self.iterable = iterable
self.start = start
self.index = start
def __iter__(self):
return self
def __next__(self):
# ... 真正的迭代逻辑 ...
pass
```
**桩代码**（`.pyi` 文件，纯类型提示）：
```python
# builtins.pyi —— 没有函数体，只有类型签名
class enumerate(Iterator[tuple[int, T]], Generic[T]):
def __init__(self, iterable: Iterable[T], start: int = 0) -> None: ...
def __iter__(self) -> Self: ...
def __next__(self) -> tuple[int, T]: ...
```
## 为什么要桩代码？
| 场景 | 原因 |
|------|------|
| **C 扩展模块** | 真实代码是 `.so`/`.pyd` 二进制，Python 解析器看不懂 |
| **类型检查** | `mypy` 需要知道参数类型、返回值类型 |
| **IDE 提示** | PyCharm/VSCode 需要知道 `enumerate` 返回 `tuple[int, T]` |
| **跨平台** | 不同系统 C 实现不同，桩代码统一接口描述 |
## 一句话
> **桩代码是"类型说明书"**，没有真实逻辑，只为告诉工具："这个函数长什么样、接受什么参数、返回什么类型"。真实跑的还是 C 写的二进制。
