Python类型提示仅用于静态分析，运行时不解析、不校验；需借助mypy等工具做静态检查，或pydantic/typeguard等库实现运行时校验。
类型提示不被 Python 运行时解析
Python 的类型提示（type hints）在默认情况下完全不会被解释器执行或验证。它们只是注释，会被编译成 __annotations__ 字典存入函数或类对象，但不会触发任何类型检查、转换或运行时行为。你写 def f(x: str) -> int:，Python 启动后照样能传入 list 或 None，毫无报错。
常见错误现象：以为加了 : Optional[str] 就能自动处理 None；或认为 -> List[int] 会让返回值被强制转成列表 —— 实际上什么都不会发生。
- 类型提示只影响 IDE 补全、静态分析工具（如 mypy、pyright）和文档生成（如 sphinx-autodoc）
-
__annotations__是纯字典，键是参数/变量名，值是原始注解表达式（可能为字符串、类型、ForwardRef等） - 从 Python 3.9 开始，
typing.List等不再是必需的，可直接用list[int]，但底层仍通过typing.get_origin()和typing.get_args()解析
静态检查工具如何“解析”类型提示
mypy、pyright 这类工具是在源码层面做 AST 遍历 + 类型推导，不是读取运行时的 __annotations__。它们会：
- 把
def foo(x: Union[str, int]) -> None:中的Union[str, int]解析为类型联合，并在调用处校验实参是否属于该联合 - 对泛型（如
dict[str, list[float]]）递归展开，识别键/值/嵌套层级的约束 - 处理字符串前向引用（
"MyClass"）时，延迟绑定到当前作用域的类定义 - 遇到
Any或未标注的变量，会放宽推导，但可能掩盖潜在问题
注意：from __future__ import annotations 会把所有注解转为字符串，推迟求值，避免循环引用，但它本身不改变解析逻辑 —— 工具仍需手动调用 typing.eval_str_annotation（或等价机制）来解析。
立即学习“Python免费学习笔记（深入）”；
运行时想真正“用上”类型提示怎么办
如果需要在运行时做类型校验（比如 API 参数解析、配置加载），必须显式调用第三方库或自己解析 __annotations__。Python 标准库不提供运行时类型检查能力。
-
pydantic：把类型提示转为数据验证规则，支持嵌套模型、默认值、序列化；但会引入额外对象实例开销 -
typeguard：装饰函数后，在调用时动态检查参数/返回值，基于__annotations__和typing模块反射解析 - 手写解析要注意：
list[int]在 Python 3.9+ 是types.GenericAlias，而typing.List[int]是typing._GenericAlias，两者需不同方式提取参数（用get_origin()/get_args()更安全） - 别直接
eval()注解字符串 —— 有安全风险，且无法处理闭包中未定义的名称
容易被忽略的解析边界
类型提示的“解析”从来不是黑盒全自动过程，很多结构根本无法被可靠还原：
-
Callable[[int, str], bool]中的参数列表是list，但具体形参名丢失，mypy 也只能检查数量与类型，不校验名字 -
Literal["a", "b"]在运行时是typing.Literal实例，但其值在 AST 阶段就被固化，无法动态扩展 -
TypedDict的字段是字面量键名，但若用字符串拼接构造键（f"{prefix}_id"），静态工具就无法识别 - 带
Protocol的鸭子类型，只在 mypy 中参与结构匹配，运行时isinstance(obj, MyProto)默认返回False（除非显式注册）
真正关键的不是“怎么解析”，而是明确场景：静态检查靠工具链，运行时约束靠显式库，两者不互通，也不能互相替代。混淆这两层，是绝大多数类型提示误用的根源。
