Python 类型提示是如何被解析的

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（除非显式注册）

真正关键的不是“怎么解析”，而是明确场景：静态检查靠工具链，运行时约束靠显式库，两者不互通，也不能互相替代。混淆这两层，是绝大多数类型提示误用的根源。