登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  文章 >  python教程

Python 3.14 annotationlib.get_annotations 怎样读取延迟注解

来源:17golang原创

时间:2026-11-20 12:06:31 423浏览 收藏

Python 3.14 把注解默认改成延迟求值后,直接读取 __annotations__ 不再是最稳妥的通用入口。需要做运行时检查、文档生成或框架适配时,优先使用 annotationlib.get_annotations(),再按场景选择值、前向引用或字符串格式。

官方文档:https://docs.python.org/3.14/library/annotationlib.html

最小选择规则:要实际类型值用 Format.VALUE;不希望未定义名称打断读取用 Format.FORWARDREF;只展示注解文本用 Format.STRING。兼容旧式字符串注解时才考虑 eval_str=True。
  • get_annotations(obj) 返回新字典,不会把继承来的类注解混入结果。
  • FORWARDREF 能把暂时解析不了的名称保留为 ForwardRef。
  • eval_str=True 会执行 eval(),不要把不可信字符串交给它。

先确定要读取哪一种注解结果

get_annotations() 可以接收函数、类和模块,也可以接收带有 __annotate__ 或 __annotations__ 的对象。Python 3.14 的延迟注解会在需要时计算,因此读取动作本身就是一次明确的策略选择。

格式返回内容适用场景
VALUE运行时对象依赖类型对象进行校验、注册或分派
FORWARDREF真实值与 ForwardRef 的组合循环引用、插件尚未导入、扫描阶段
STRING接近源码写法的字符串文档、日志和不需要执行注解的展示
annotationlib get_annotations 与三种 Format 的静态关系说明图
图1:结构说明图展示 get_annotations、三种 Format、ForwardRef 与 __annotate__ 的关系,不是截图或运行证据。

用 get_annotations 读取三种格式

下面的函数故意引用尚未定义的 LaterType,用来区分三种读取策略。示例只展示调用关系;实际项目应根据自己的注册流程决定何时把前向引用解析成真实对象。

from annotationlib import Format, get_annotations

def load(value: LaterType) -> list[str]:
    # 延迟注解允许名称在函数定义之后再出现
    return [str(value)]

class LaterType:
    pass

# VALUE 适合需要真实类型对象的运行时逻辑
runtime_values = get_annotations(load, format=Format.VALUE)

# FORWARDREF 在名称无法解析时保留 ForwardRef
safe_values = get_annotations(load, format=Format.FORWARDREF)

# STRING 只取可读文本,不把文本当成可执行类型
display_values = get_annotations(load, format=Format.STRING)

print(runtime_values["value"])
print(safe_values["value"])
print(display_values["value"])

这里的关键不是把三次结果硬编码成同一种类型,而是让调用方明确表达意图:运行时注册器通常需要 VALUE,扫描器更适合 FORWARDREF,文档工具则可以使用 STRING。每次调用都会得到一个新的等价字典,调用方可以放心对返回值做局部整理。

遇到未定义名称时怎么保留 ForwardRef

如果直接使用默认的 Format.VALUE,注解表达式中的未定义名称可能抛出 NameError。这并不表示函数签名错误,只表示当前读取时机还不能把所有名字变成运行时对象。

from annotationlib import Format, ForwardRef, get_annotations

def convert(node: MissingNode) -> Result:
    # 这里只声明类型关系,不要求扫描阶段已经导入所有模型
    return node

annotations = get_annotations(convert, format=Format.FORWARDREF)
node_type = annotations["node"]

if isinstance(node_type, ForwardRef):
    # 记录待解析名称,等插件加载完成后再决定是否 evaluate
    print(node_type.__forward_arg__)

result_type = annotations["return"]

ForwardRef 可以通过 __forward_arg__ 查看表达式文本;如果后续确实具备作用域,再调用它的 evaluate()。把“收集注解”和“执行注解”拆开,能避免插件扫描、循环类型或部分导入阶段被偶发的名称缺失打断。

eval_str 与兼容边界

eval_str 主要服务于 from __future__ import annotations 产生的字符串注解。它只能与 Format.VALUE 一起使用;设为 True 后,字符串会交给 eval(),必要时通过 globals 和 locals 提供名称空间。

from __future__ import annotations

from annotationlib import get_annotations

class User:
    pass

def save(user: User) -> list[User]:
    # 兼容字符串化注解时,显式提供当前模块命名空间
    return [user]

values = get_annotations(
    save,
    eval_str=True,
    globals=globals(),
    locals=locals(),
)
print(values["user"])
print(values["return"])
eval_str、globals、locals 与字符串注解的静态关系说明图
图2:结构图对比字符串注解、eval_str、globals/locals 和 VALUE 的关系,不代表某次命令的真实输出。

新代码如果只是展示或索引注解,优先用 Format.STRING,不必为了得到文本而执行表达式。对于来源不可信的模块或动态生成对象,更不要无条件设置 eval_str=True;先确认代码来源和名称空间,再决定是否解析。

常见问题

Python 3.13 能直接导入 annotationlib 吗?

该模块随 Python 3.14 加入标准库。需要兼容旧版本时,应使用项目明确支持的回移实现或保留旧的适配层,不要假定标准库模块在 3.13 中存在。

为什么不直接访问 __annotations__?

直接属性访问缺少格式选择,也容易把延迟求值、前向引用和类继承边界交给调用方自行处理。通用 introspection 代码使用 get_annotations() 更容易把策略写在调用点。

参考资料

Python 3.14 annotationlib:https://docs.python.org/3.14/library/annotationlib.html

Python 3.14 新特性:https://docs.python.org/3.14/whatsnew/3.14.html

PEP 749:https://peps.python.org/pep-0749/

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>