当前位置：首页 > 文章列表 > 文章 > python教程 > 从 typing.Annotated 中移除注解的实用方法

从 typing.Annotated 中移除注解的实用方法

2025-11-20 14:51:23 0浏览收藏

“纵有疾风来，人生不言弃”，这句话送给正在学习文章的朋友们，也希望在阅读本文《从 typing.Annotated 中移除注解的实用方法》后，能够真的帮助到大家。我也会在后续的文章中，陆续更新文章相关的技术文章，有好的建议欢迎大家在评论留言，非常感谢！

本文探讨了在Python类型提示中使用 `typing.Annotated` 时，如何有效移除其附加的元数据，以获取纯净的类型结构。通过介绍一种基于递归遍历类型树的解决方案，该方法能够将嵌套的 `Annotated` 类型转换为其对应的裸类型，从而满足在某些场景下需要无注解类型表示的需求，同时保留原始注解供其他用途。

理解 typing.Annotated 及其挑战

typing.Annotated 是 Python typing 模块中的一个强大工具，它允许开发者在类型提示中附加额外上下文或元数据，而这些元数据在运行时是可访问的。例如，你可以用它来描述一个类型变量的单位、验证规则或文档字符串。

from typing import Annotated, tuple, list, float

Point3D = Annotated[tuple[float, float, float], "A 3D Point"]
Points = Annotated[list[Point3D], "A collection of points"]

print(Points)

当直接打印 Points 这样的类型别名时，输出会包含所有嵌套的 Annotated 信息：

typing.Annotated[list[typing.Annotated[tuple[float, float, float], 'A 3D Point']], 'A collection of points']

在某些场景下，我们可能需要获取这些类型别名的“纯净”形式，即不包含任何 Annotated 元数据的类型结构。例如，在生成文档、进行类型比较或与不支持 Annotated 的外部系统交互时，我们可能只需要 list[tuple[float, float, float]] 这样的裸类型。

尝试使用 typing.get_args(Points)[0] 只能剥离最外层的 Annotated，但如果内部类型仍然是 Annotated，它们会保持不变，如 list[typing.Annotated[tuple[float, float, float], 'A 3D Point']]。这表明我们需要一种更深层次的机制来处理嵌套的注解。

解决方案：递归遍历类型树

解决这个问题的核心思想是递归地遍历类型对象的结构（即类型树），并在遇到 Annotated 节点时，将其替换为其第一个参数（即实际的类型），然后继续处理。对于其他泛型类型（如 list、tuple 等），则递归地处理它们的类型参数。这种方法比使用正则表达式来移除注解更为健壮和准确，因为它是基于类型系统的结构而非字符串匹配。

实现 convert_annotated_to_bare_types 函数

我们可以编写一个辅助函数 convert_annotated_to_bare_types 来实现这一逻辑。该函数将接受一个类型对象作为输入，并返回一个移除了所有 Annotated 元数据的类型对象。

from typing import Annotated, get_args, get_origin, TypeVar

def convert_annotated_to_bare_types(type_object: type) -> type:
  """
  递归地将类型对象中所有的 typing.Annotated 节点转换为其对应的裸类型。

  Args:
    type_object: 待处理的类型对象。

  Returns:
    移除了所有 Annotated 注解的类型对象。
  """
  # get_origin(X[Y, Z, ...]) 返回 X (如 list, tuple, Annotated)
  # get_args(X[Y, Z, ...]) 返回 (Y, Z, ...)
  # 对于非泛型或无参数的类型，get_origin 返回 None，get_args 返回 ()
  origin, args = get_origin(type_object), get_args(type_object)

  if origin is None:
    # 如果没有 origin，说明这不是一个泛型类型（如 int, str, float）
    # 或者是一个 TypeVar，直接返回其本身。
    # TypeVar 自身没有 args 或 origin，但其 __origin__ 属性可能为 None
    # 并且 get_origin(TypeVar('T')) 也返回 None。
    return type_object

  if origin is Annotated:
    # 如果 origin 是 Annotated，我们只关心它的第一个参数（即实际的类型）。
    # 递归地处理这个实际类型，以确保其内部的 Annotated 也被移除。
    bare_type = get_args(type_object)[0]
    return convert_annotated_to_bare_types(bare_type)

  # 对于其他泛型类型（如 list, tuple, dict, Union 等），
  # 递归地处理其所有类型参数。
  converted_args = [
    convert_annotated_to_bare_types(arg) for arg in args
  ]

  # 使用 origin[*converted_args] 重新构造泛型类型。
  # 例如，list[*[int, str]] 会变成 list[int, str]
  # 注意：Python 3.9+ 支持此语法，早期版本可能需要 type(origin)(*converted_args) 或其他方式。
  return origin[*converted_args]

代码解析

get_origin(type_object) 和 get_args(type_object): 这两个 typing 模块的函数是处理泛型类型的关键。
- get_origin 返回一个泛型类型（如 list、tuple、Annotated）的“基础”类型。对于非泛型类型（如 int、str）或 TypeVar，它返回 None。
- get_args 返回泛型类型的所有类型参数。例如，get_args(list[int]) 返回 (int,)。
基本情况（origin is None）: 如果 type_object 没有 origin（即它是一个像 int、str 这样的基本类型，或者是一个 TypeVar），那么它不需要进一步处理，直接返回其本身。
Annotated 情况（origin is Annotated）: 这是我们关注的核心。如果 origin 是 Annotated，我们知道它的第一个参数就是它所注解的实际类型。我们获取这个参数，并对其进行递归调用 convert_annotated_to_bare_types，以确保如果这个实际类型本身也是一个 Annotated 或包含 Annotated，也能被正确处理。
泛型情况（其他 origin）: 对于 list、tuple、dict、Union 等其他泛型类型，我们遍历它们的每个类型参数 (args)，并对每个参数递归调用 convert_annotated_to_bare_types。然后，我们使用 origin[*converted_args] 将原始的 origin 和处理后的参数重新组合成一个新的泛型类型。

示例用法

让我们用之前定义的 Points 类型别名来测试这个函数：

# 重新定义类型别名，确保 Annotated 导入
from typing import Annotated, tuple, list, float

Point3D = Annotated[tuple[float, float, float], "A 3D Point"]
Points = Annotated[list[Point3D], "A collection of points"]

# 使用我们的函数
bare_points_type = convert_annotated_to_bare_types(Points)
print(bare_points_type)

输出将是：

list[tuple[float, float, float]]

这正是我们想要的结果：所有 Annotated 元数据都被成功移除，只留下纯净的类型结构。

注意事项与总结

运行时操作: convert_annotated_to_bare_types 是一个运行时函数。它在程序执行时检查和修改类型对象，而不是在类型检查阶段（如 MyPy）。
保持原始注解: 这种方法不会修改原始的 Point3D 或 Points 类型别名。它们仍然保留了所有的 Annotated 元数据，这意味着你可以在需要时通过 get_args(Point3D)[1] 等方式访问这些元数据。这个函数只是生成了一个新的、无注解的类型表示。
兼容性: get_origin 和 get_args 在 Python 3.8+ 中表现稳定。对于更早的版本，可能需要不同的方法来解析泛型类型。origin[*converted_args] 的语法在 Python 3.9+ 中直接支持，在早期版本中可能需要 type(origin)(*converted_args) 或其他变通方法。
通用性: 该函数对于任意深度的嵌套 Annotated 类型以及各种泛型类型都有效，提供了一个通用且健壮的解决方案。

通过这种递归遍历的方式，我们可以优雅地从复杂的类型提示中提取出其核心的类型结构，满足不同场景下的需求，同时避免了使用不稳定的正则表达式来处理结构化数据。

终于介绍完啦！小伙伴们，这篇关于《从 typing.Annotated 中移除注解的实用方法》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！