Python 编程最佳实践

类型注解

• 始终为函数参数和返回值添加类型注解
• 使用 Type | None 替代 Optional[Type]（Python 3.10+）
• 在文件顶部添加 from __future__ import annotations，启用延迟类型求值
• TypeVar 命名以 T 为后缀：ChatResponseT = TypeVar("ChatResponseT", bound=ChatResponse)
• 只读输入参数使用 Mapping 而非 MutableMapping
• 对于内部调用的方法，优先使用 # type: ignore[具体规则] 而非多余的类型转换或 isinstance 检查；注释需同时兼顾 mypy 和 pyright，避免遗漏其他错误

from __future__ import annotations
from collections.abc import Mapping
from typing import TypeVar

ResponseT = TypeVar("ResponseT", bound=BaseResponse)