当前位置:首页 > 文章列表 > 文章 > python教程 > Python 3.14 annotationlib.get_annotations 怎样读取延迟注解

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

来源:17golang原创 2026-11-20 12:06:31 0浏览 收藏

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删除
Python 3.14 跨解释器 Queue.put 的阻塞与 QueueFull 处理方案Python 3.14 跨解释器 Queue.put 的阻塞与 QueueFull 处理方案
上一篇
Python 3.14 跨解释器 Queue.put 的阻塞与 QueueFull 处理方案
Java MethodHandles.filterArguments 怎样按位置预处理方法参数
下一篇
Java MethodHandles.filterArguments 怎样按位置预处理方法参数
查看更多
最新文章
查看更多
课程推荐
  • 前端进阶之JavaScript设计模式
    前端进阶之JavaScript设计模式
    设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
    543次学习
  • GO语言核心编程课程
    GO语言核心编程课程
    本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
    516次学习
  • 简单聊聊mysql8与网络通信
    简单聊聊mysql8与网络通信
    如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
    500次学习
  • JavaScript正则表达式基础与实战
    JavaScript正则表达式基础与实战
    在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
    487次学习
  • 从零制作响应式网站—Grid布局
    从零制作响应式网站—Grid布局
    本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
    485次学习
查看更多
AI推荐
  • PubMedQA数据集详解:生物医学问答基准、功能与应用指南
    PubMedQA
    深入了解PubMedQA生物医学问答数据集,涵盖其核心功能、使用方法及在临床决策、药物研发等场景的应用,助力提升NLP模型性能。
    1142次使用
  • H2O EvalGPT:开源LLM大模型评估与排行榜工具
    H2O EvalGPT
    H2O EvalGPT是H2O.ai推出的开源LLM评估平台,提供详细的大模型性能排行榜、行业特定基准测试及A/B测试功能,助您快速选择最适合项目的高性能大语言模型。
    1128次使用
  • LMArena是什么?伯克利AI模型评估平台使用指南与功能解析
    LMArena
    LMArena是加州大学伯克利分校推出的AI模型匿名评测平台。通过盲测投票机制,用户可对比不同大模型回答并生成实时排行榜,助力开发者优化模型及用户选择最佳AI工具。
    1304次使用
  • 斯坦福HELM:大语言模型Holistic Evaluation整体评估框架详解
    HELM
    深入了解斯坦福推出的HELM(Holistic Evaluation of Language Models)大模型评测体系。本文解析其核心功能、安装配置步骤及应用场景,涵盖准确性、公平性、鲁棒性等多维度指标,助力开发者全面优化语言模型性能。
    1243次使用
  • MMBench详解:多模态大模型基准测试、功能特点与使用指南
    MMBench
    MMBench是由上海人工智能实验室等机构联合推出的多模态基准测试平台,提供细粒度能力评估、大规模数据集及VLMEvalKit工具。本文详细介绍其核心功能、安装使用方法及应用场景,助力开发者全面评估多模态模型性能。
    1094次使用
微信登录更方便
  • 密码登录
  • 注册账号
登录即同意 用户协议 和 隐私政策
返回登录
  • 重置密码