Python中Annotated元数据访问方法

欢迎各位小伙伴来到golang学习网，相聚于此都是缘哈哈哈！今天我给大家带来《Python 中访问 Annotated 元数据方法》，这篇文章主要讲到等等知识，如果你对文章相关的知识非常感兴趣或者正在自学，都可以关注我，我会持续更新相关文章！当然，有什么建议也欢迎在评论留言提出！一起学习！

本文介绍如何通过 __metadata__ 属性安全、标准地提取 typing.Annotated 类型注解中携带的自定义元数据（如文档对象、校验规则或配置实例），避免字符串化陷阱，实现运行时类型增强功能。

在 Python 3.9+ 中，typing.Annotated 提供了一种标准化方式，为类型添加任意元数据（metadata），而这些元数据在运行时并非被丢弃或转为字符串，而是以元组形式完整保留在类型对象的 __metadata__ 属性中。这使得你可以在反射（reflection）场景下（如自动生成 API 文档、参数校验、序列化配置等）可靠地访问它们。

以下是一个完整示例，展示如何从 Annotated[str, B(x="foo")] 中提取并使用 B 实例：

from typing import Annotated, get_args
import inspect
from dataclasses import dataclass

@dataclass
class B:
    x: str

@dataclass
class A:
    y: Annotated[str, B(x="foo"), "This is a user-facing description"]

# 获取运行时解析后的注解字典（推荐：使用 get_type_hints 或 inspect.get_annotations）
annotations = inspect.get_annotations(A, eval_str=True)
annotated_type = annotations["y"]

# ✅ 正确方式：访问 __metadata__ 属性（标准、稳定、无需解析字符串）
if hasattr(annotated_type, "__metadata__"):
    metadata = annotated_type.__metadata__  # 类型：tuple
    print("Metadata tuple:", metadata)           # 输出: (B(x='foo'), 'This is a user-facing description')

    # 提取第一个元数据项（即 B 实例）
    if metadata and isinstance(metadata[0], B):
        b_instance = metadata[0]
        print("B.x =", b_instance.x)              # 输出: B.x = foo

    # 可遍历所有元数据（支持多个标签）
    for i, item in enumerate(metadata):
        print(f"Metadata[{i}]: {type(item).__name__} = {item}")

⚠️ 重要注意事项：

• ❌ 不要尝试用 str()、正则或 eval() 解析 repr(annotated_type) —— 这是脆弱且不安全的；
• ✅ __metadata__ 是官方定义的公有协议属性（见 Python 官方文档），保证在所有兼容实现中可用；
• ? 若需获取原始 Annotated 的所有参数（包括基础类型），可使用 get_args(annotated_type)，它返回 (str, B(x="foo"), "description")；但 __metadata__ 更语义明确，专用于元数据；
• ? inspect.get_annotations(..., eval_str=True) 是推荐方式，确保字符串化注解（如 "str"）被正确求值，避免 ForwardRef 问题。

总结来说，Annotated[T, meta1, meta2] 的设计初衷就是支持运行时元编程——__metadata__ 就是你通往类型“附加信息”的标准接口。善用它，即可构建类型驱动的文档生成器、验证框架或配置绑定系统，真正实现「类型即配置」。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python中Annotated元数据访问方法》文章吧，也可关注golang学习网公众号了解相关技术文章。