Python 存根文件(.pyi)简介与实战案例及类型提示的高级指南

# example.pyi - 接口定义
def process_data(data: list[dict]) -> pd.DataFrame: ...  # 只有签名没有实现
class DatabaseConnection:
    timeout: int = 10
    def query(self, sql: str) -> list[tuple]: ...

# 模块级变量
API_URL: str
# 函数定义（无实现体）
def fetch_data(url: str, timeout: int = 5) -> bytes: ...
# 类定义（方法只有签名）
class DataProcessor:
    cache_size: int = 100
    def __init__(self, config: dict) -> None: ...
    @staticmethod
    def normalize(input: str) -> str: ...
    def process(self, data: Iterable) -> list: ...

# 正确
def calculate(a: int, b: int) -> float: ...
# 错误
def calculate(a: int, b: int) -> float: pass  # 不合法

def encrypt(input: bytes, *, key: bytes) -> bytes: ...  # 匿名参数

if sys.version_info >= (3, 10):
    from typing import ParamSpec
    P = ParamSpec('P')
else:
    P = TypeVar('P')  # 向后兼容

from typing import TypeVar, Generic
T = TypeVar('T')
K = TypeVar('K')
V = TypeVar('V')
class CustomDict(Generic[K, V]):
    def __init__(self) -> None: ...
    def __getitem__(self, key: K) -> V: ...
    def __setitem__(self, key: K, value: V) -> None: ...
class TypedList(list, Generic[T]):
    def append(self, item: T) -> None: ...
    def first(self) -> T: ...

from typing import overload
@overload
def parse(input: str) -> dict: ...
@overload
def parse(input: bytes, encoding: str = "utf-8") -> dict: ...
def parse(input): ...  # 实际实现存在其他文件

UserId = int
Email = NewType('Email', str)
def register_user(name: str, contact: Email | UserId) -> None: ...

Point2D = tuple[float, float]
Point3D = tuple[float, float, float]
def midpoint(a: Point2D | Point3D, b: Point2D | Point3D) -> Point2D | Point3D: ...

# numpy.core.multiarray.pyi
def array(obj: object, dtype: DtypeLike | None = None) -> ndarray: ...

# requests.pyi
class Response:
    status_code: int
    text: str
    def json(self) -> Any: ...
def get(url: str, params: dict | None = None, **kwargs) -> Response: ...

# database/interface.pyi
class AbstractConnection(Protocol):
    def execute(self, sql: str, params: tuple = ...) -> Cursor: ...
# database/postgres.py - 实际实现
class PostgresConnection(AbstractConnection):
    def execute(self, sql: str, params: tuple = ()) -> PG_Cursor: ...

# 为整个包生成存根
stubgen -p requests -o ./stubs
# 目录结构示例
stubs/
  requests/
    __init__.pyi
    api.pyi
    sessions.pyi

// .idea/misc.xml
<component name="PyStubPackages">
  <package name="requests" path="$PROJECT_DIR/stubs/requests" />
</component>

// settings.json
{
  "python.analysis.stubPath": "typings",
  "python.analysis.useLibraryCodeForTypes": false
}

# mypy.ini
[mypy]
strict = true
mypy_path = stubs/
[report]
generated = true  # 包含自动生成存根

project/
  src/            # 实现代码
  stubs/          # 存根目录
    numpy/
      __init__.pyi
  pyproject.toml
  mypy.ini

# 结构示例
mypackage-stubs/
  package/
    __init__.pyi
    module1.pyi
  py.typed
  setup.cfg

# setup.cfg
[metadata]
name = mypackage-stubs
version = 1.0.0

mypy --show-traceback --verbose program.py

reveal_type(some_variable)  # mypy显示推断类型

# custom_pandas.pyi
import pandas as pd
def read_bigquery(sql: str, project: str | None) -> pd.DataFrame: ...
def to_feather(df: pd.DataFrame, path: PathLike) -> None: ...

# fields.pyi
from django.db.models import Field
class EncryptedField(Field):
    def __init__(self, key: str | bytes, *args, **kwargs) -> None: ...
    def deconstruct(self) -> tuple[str, str, list, dict]: ...

# responses.pyi
from pydantic import BaseModel
class APIResponse(BaseModel):
    success: bool
    data: object | None
    error: dict | None = None