Python - PEP 749 – PEP 649 的实现补充

原创已于 2025-11-10 10:21:35 修改 · 788 阅读

23 ·

CC 4.0 BY-SA版权

文章标签：

#python #mysql #java

于 2025-10-20 05:10:05 首次发布

Python PEP 专栏收录该内容

37 篇文章

订阅专栏

Python3.8

Conda

Python

Python 是一种高级、解释型、通用的编程语言，以其简洁易读的语法而闻名，适用于广泛的应用，包括Web开发、数据分析、人工智能和自动化脚本

Python - PEP 749 – PEP 649 的实现补充

摘要

本 PEP 补充了 PEP 649 的规范，具体包括：

from __future__ import annotations（PEP 563）将至少保留到 Python 3.13 生命周期结束，之后会弃用并最终移除。
新增标准库模块 annotationlib，为注解提供工具，包括 get_annotations()、注解格式枚举、ForwardRef 类及辅助的 __annotate__ 调用函数。
REPL 环境下的注解与模块级注解一样延迟求值。
明确诸如 classmethod() 和 functools.wraps() 等包装器提供注解时的行为。
不再用代码标志位区分“可在伪 globals 环境执行的 annotate”，而是新增 VALUE_WITH_FAKE_GLOBALS 格式供第三方实现表明支持的格式。
直接删除 __annotations__ 属性时也会清除 __annotate__。
支持 PEP 695、PEP 696 增加的类型别名值、类型参数约束/默认值等用类似 PEP 649 的延迟求值方式。
SOURCE 格式更名为 STRING，提升清晰度。
条件定义的类和模块注解能正确处理。
若在部分执行的模块访问注解，返回已执行部分的注解，但不缓存。

动机

PEP 649 为 Python 注解提供了更优雅的延迟求值机制，极大提升了类型提示和运行时类型系统的可用性、优雅性和能力。PEP 649 最初计划在 3.10 实现，2023 年被正式接受，但实现延期至 3.14。

在实现过程中发现 PEP 649 部分细节未明确定义，个别角落行为也有值得改进之处。本 PEP 不替代而是补充 PEP 649，对部分细节加以完善，提升整体用户体验。

`from future import annotations` 的未来

PEP 563 引入 future import annotations，让所有注解都变为字符串。PEP 649 提出无需 future import 的新方案，并计划弃用 563，但未具体说明弃用步骤。

规范

建议的弃用计划如下：

Python 3.14 及以前，from __future__ import annotations 行为不变，注解全为字符串。
- 若激活该 future import，带注解对象的 __annotate__ 返回字符串形式（VALUE 格式），与 __annotations__ 保持一致。
在不支持 PEP 649 的最后一个 Python 版本（预计为 3.13）停止维护后，开始弃用该 future import。使用时编译器发出 DeprecationWarning。弃用最早从 3.13 EOL 后第一个大版本开始，也可延后。
至少两个大版本后，彻底移除该 future import，注解始终按 PEP 649 延迟求值。继续使用则抛出 SyntaxError。

被拒绝的方案

立即让 future import 失效：会破坏那些依赖 forwardref 且 eager 求值的代码，影响面广，不可行。
立即弃用 future import：许多库依赖该特性实现前向引用，若立即弃用无法兼容所有 Python 版本且避免警告，不现实。
永久保留 future import：会导致 Python 语义永远分裂为两种模式，不利于语言一致性。
未来让 future import 变为无操作：不如明确要求用户移除 future import，避免歧义。

新增 annotationlib 模块

PEP 649 建议把注解相关工具加入 inspect，但该模块过大且依赖众多，性能不佳。我们决定新建 annotationlib，专门提供注解工具，也便于后续扩展。

PEP 649 建议用 typing.ForwardRef 实现 FORWARDREF 格式，但现有 typing.ForwardRef 与 typing 模块耦合，且对外文档不足但被三方库大量依赖。我们将其替换为 annotationlib.ForwardRef，并兼容原有用法。保留 _evaluate 方法但标记为弃用，同时在 typing 新增 evaluate_forward_ref，专门用于类型提示下的前向引用求值。

新增 annotationlib.call_annotate_function 辅助调用 __annotate__，便于如 typing.NamedTuple 之类在类构造过程中部分求值注解。

规范

标准库新增 annotationlib：

get_annotations()：获取函数、模块、类注解，将取代 inspect.get_annotations()（后者将委托前者，暂不弃用）。
get_annotate_from_class_namespace(namespace)：从类命名空间获取 __annotate__。
Format：注解格式枚举，含 VALUE、VALUE_WITH_FAKE_GLOBALS、FORWARDREF、STRING（原 PEP 649 的 VALUE、FORWARDREF、SOURCE）。
ForwardRef：前向引用类，含 __forward_arg__、evaluate() 等。
call_annotate_function(func, format)：辅助调用 __annotate__，若不支持给定格式则自动用 fake globals 环境。
call_evaluate_function(func, format)：类似上，但用于 PEP 695/696 的延迟属性求值。
annotations_to_string(annotations)：将注解 dict 全部转为字符串形式。
type_repr(value)：单个对象转字符串，类型用完全限定名，其他用 repr()。

typing 模块新增 evaluate_forward_ref，递归求值前向引用，特化于类型提示。

PEP 649 的 VALUE、FORWARDREF、SOURCE 等常量不会作为 inspect 全局成员，只能通过 annotationlib.Format.VALUE 等访问。

被拒绝的方案

其他名称（如 annotation、annotools、annotationslib、annotationlib 等），最终选择了 annotationlib。
加入 inspect/typing/types 模块，理由同上，不便于隔离注解与类型提示、类型本身。
作为三方包开发，标准库自身已需用这些功能，直接内置更好。
先做成私有模块，后公开。实际标准库与三方很快都会用，直接设计正式 API 更合适。

REPL 行为

PEP 649 原计划 REPL 下注解立即求值，与模块行为不同。但这样实现更复杂且会让用户疑惑。我们建议 REPL 下也延迟求值，与模块一致。

每一行含注解的全局代码会生成新的 __annotate__，前一行的 __annotate__ 会被覆盖。REPL 没有全局命名空间的 __annotations__ 键。

类和函数定义同样延迟注解求值，annotationlib 可用于 introspect。

包装器对象的注解

标准库包装器（如 functools.wraps、classmethod、staticmethod）应：

尽可能延迟求值，保持一致性和兼容性。
functools.update_wrapper/wraps 只复制 __annotate__，__annotations__ 用复制的 __annotate__。
classmethod/staticmethod 构造器提供可写的 __annotate__ 和 __annotations__，读取时从被包裹对象取并缓存，写入时只改自身，不影响被包裹对象。

元类与注解

发现 metaclass 与 class 注解交互存在老 bug，比如 metaclass 的注解会意外影响子类。PEP 649 延迟求值后，__annotate__、__annotations__ 只在特定条件下设置，依赖 type 描述符，若 metaclass 字典有同名键会导致描述符失效，出现异常。

最终方案：在类字典存储 __annotate__/__annotations__ 时用内部专用名，避免与 type 描述符冲突。用户不应直接访问类字典获取注解，应用 annotationlib.get_annotate_from_class_namespace。

被拒绝的方案

总是/从不在类字典插入注解相关键，或用特殊描述符，都有实现/兼容性/复杂性权衡。最终选择内部隐藏存储。

新增 VALUE_WITH_FAKE_GLOBALS 格式

PEP 649 原建议用 code flag 指示 __annotate__ 是否能在 fake globals 环境运行。我们改为新增枚举值 VALUE_WITH_FAKE_GLOBALS，编译器生成的 annotate 函数支持该格式，第三方手写的不支持时应抛 NotImplementedError。