深度解析：如何在Python中递归剥离typing.Annotated类型注解

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

深度解析：如何在Python中递归剥离typing.Annotated类型注解

2025-11-05

浏览次数：次

返回列表

深度解析：如何在Python中递归剥离typing.Annotated类型注解

`typing.annotated`在python中用于为类型提示附加元数据，但在某些场景下，我们需要获取其纯粹的、不含注解的原始类型结构。本文将详细介绍一种无需正则表达式的递归方法，通过遍历类型提示树，识别并剥离所有`annotated`包装，从而还原出底层类型，并提供示例代码和详细解释，确保类型结构的准确还原。

理解 typing.Annotated 及其应用场景

typing.Annotated 是 Python 3.9 引入的一个强大特性，它允许开发者在类型提示中嵌入额外的元数据，而这些元数据不会影响类型检查器的行为。例如，你可以为 int 类型添加一个描述，说明它代表一个用户ID，或者为 str 类型添加一个正则模式，指示其预期格式。

from typing import Annotated

UserID = Annotated[int, "The unique identifier for a user"]
Email = Annotated[str, "A valid email address", r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"]

def get_user_id() -> UserID:
    # ... implementation ...
    return 123

def validate_email(email: Email) -> bool:
    # ... implementation using the regex metadata ...
    return True

这种机制在运行时可以通过 typing.get_args 等函数访问这些元数据，为类型提示赋予更丰富的语义，常用于API文档生成、数据验证或代码生成等场景。

问题：获取纯粹的类型结构

尽管 Annotated 提供了极大的灵活性，但在某些情况下，我们可能需要获取一个类型提示的“裸”版本，即剥离所有 Annotated 包装及其元数据，只保留其核心的类型结构。考虑以下复杂类型别名：

from typing import Annotated, tuple, list

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

当我们尝试直接打印 Points 时，会得到一个包含所有 Annotated 信息的冗长字符串：

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

如果我们的目标是仅获取 list[tuple[float, float, float] | list[float]] 这样的纯粹类型结构，直接使用 typing.get_args(Points)[0] 只能剥离最外层的 Annotated，内部嵌套的 Annotated 仍然存在，例如：

list[typing.Annotated[tuple[float, float, float], 'A 3D Point'] | list[float]]

这表明我们需要一种更深层次的机制来递归地处理嵌套的 Annotated 类型。

解决方案：递归遍历类型树并剥离注解

解决此问题的关键在于理解类型提示在运行时可以被视为一个树状结构，其中泛型类型（如 list、tuple、Union）是节点，它们的类型参数是子节点。typing 模块提供了 get_origin 和 get_args 函数，用于在运行时检查这些类型结构。

typing.get_origin(type_object): 返回泛型类型（如 list、tuple）的原始类型，对于非泛型类型或 Annotated，它返回 None 或 Annotated 本身。
typing.get_args(type_object): 返回泛型类型（如 list[int]）的类型参数（如 (int,)），对于 Annotated[T, metadata]，它返回 (T, metadata)。

我们可以利用这两个函数，编写一个递归函数来遍历整个类型树，并在遇到 Annotated 类型时，将其替换为其第一个参数（即其所注解的实际类型），然后继续递归处理。

VALL-E

VALL-E是一种用于文本到语音生成 (TTS) 的语言建模方法

134 查看详情 VALL-E

示例代码

from typing import Annotated, get_args, get_origin, Union

def convert_annotated_to_bare_types(type_object: type) -> type:
  """
  递归地将类型对象中的所有 typing.Annotated 包装剥离，
  还原出纯粹的底层类型结构。
  """
  # 获取类型对象的原始类型和类型参数
  # 对于 X[Y, Z, ...]，get_origin 返回 X，get_args 返回 (Y, Z, ...)
  # 对于非泛型或无参数类型，get_origin 返回 None，get_args 返回 ()
  origin, args = get_origin(type_object), get_args(type_object)

  # 基本情况：如果类型没有原始类型（即不是泛型或Annotated），直接返回
  if origin is None:
    return type_object

  # 特殊情况：如果原始类型是 Annotated
  if origin is Annotated:
    # Annotated[T, metadata] 的第一个参数是其所注解的实际类型 T
    bare_type = get_args(type_object)[0]
    # 递归处理这个实际类型，以防它内部也包含 Annotated
    return convert_annotated_to_bare_types(bare_type)

  # 递归情况：如果原始类型是其他泛型（如 list, tuple, Union 等）
  # 遍历其所有类型参数，并递归地剥离其中的 Annotated
  converted_args = [
    convert_annotated_to_bare_types(arg) for arg in args
  ]

  # 使用原始类型和处理后的参数重建泛型类型
  # 例如，list[int, str] 将被重建为 list[int, str]
  # 对于 Union 类型，需要特殊处理，因为 Union[*args] 语法在 Python 3.9+ 才能直接用，
  # 且 Union 的参数如果只有一个，Union 本身会消失。
  # 考虑到 Union 在 Python 3.10+ 可以用 `|` 运算符，这里使用 `origin[*converted_args]`
  # 是兼容的通用做法，它会自动处理 Union 的特殊情况。
  if origin is Union and len(converted_args) == 1:
      return converted_args[0] # Union[X] 等同于 X

  return origin[*converted_args]

函数工作原理详解

基本情况 (origin is None):
- 如果 get_origin(type_object) 返回 None，这表示 type_object 是一个非泛型类型（如 int, str, float）或者一个已解析到最底层的类型。在这种情况下，它不可能包含 Annotated 包装，因此直接返回 type_object。
Annotated 类型处理 (origin is Annotated):
- 如果 get_origin(type_object) 返回 Annotated，说明我们遇到了一个 Annotated[T, metadata] 结构。
- get_args(type_object)[0] 会提取出 Annotated 所包装的实际类型 T。
- 然后，我们对这个 T 再次调用 convert_annotated_to_bare_types 进行递归处理，以确保 T 内部如果也包含 Annotated，也能被正确剥离。
其他泛型类型处理 (else 块):
- 如果 get_origin(type_object) 返回 list, tuple, dict, Union 等其他泛型类型，这意味着 type_object 是一个像 list[int] 或 Union[str, int] 这样的结构。
- 我们通过列表推导式 [convert_annotated_to_bare_types(arg) for arg in args]，对该泛型类型的所有类型参数 args 进行递归调用，确保其子类型中的 Annotated 也被剥离。
- 最后，使用 origin[*converted_args] 语法，将原始的泛型类型（如 list）与经过处理后的类型参数重新组合，形成一个新的、不含 Annotated 的泛型类型。
- 对于 Union 类型，如果最终只剩一个参数，如 Union[str]，Python 会将其简化为 str，因此我们添加了 if origin is Union and len(converted_args) == 1: return converted_args[0] 的优化处理。

示例用法

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

# 定义原始类型
Point3D = Annotated[tuple[float, float, float], "A 3D Point"]
Points = Annotated[list[Point3D | list[float]], "A collection of points"]

# 打印原始类型
print(f"原始类型: {Points}")
# 预期输出: typing.Annotated[list[typing.Annotated[tuple[float, float, float], 'A 3D Point'] | list[float]], 'A collection of points']

# 调用函数剥离注解
bare_points_type = convert_annotated_to_bare_types(Points)

# 打印剥离注解后的类型
print(f"剥离注解后的类型: {bare_points_type}")
# 预期输出: list[tuple[float, float, float] | list[float]]

输出结果：

原始类型: typing.Annotated[list[typing.Annotated[tuple[float, float, float], 'A 3D Point'] | list[float]], 'A collection of points']
剥离注解后的类型: list[tuple[float, float, float] | list[float]]

可以看到，所有嵌套的 Annotated 包装及其元数据都被成功剥离，还原出了我们所需的纯粹类型结构。

注意事项与总结

运行时操作: 这种剥离 Annotated 的方法是一个运行时操作。它不会改变原始类型提示的定义，而是在运行时生成一个新的类型对象，该对象不包含 Annotated 信息。原始的 Annotated 类型定义仍然保留，因此你可以在需要其元数据的地方继续使用它们。
无需正则表达式: 这种方法避免了使用正则表达式解析类型字符串的复杂性和潜在错误。通过 get_origin 和 get_args 直接操作类型对象，更加健壮和可靠。
通用性: get_origin 和 get_args 是处理 Python 类型提示的通用工具，这个递归遍历的模式可以扩展到其他复杂的类型操作中。
Python 版本兼容性: typing.Annotated 在 Python 3.9+ 中可用。get_origin 和 get_args 在较早的 Python 版本中也存在，但其行为可能略有不同，尤其是在处理 Union 和其他复杂泛型时。提供的代码在 Python 3.9+ 环境下表现良好。

通过这种递归遍历的方式，我们可以优雅且高效地从复杂的类型提示中剥离 typing.Annotated 包装，从而获得一个干净、纯粹的类型结构，满足特定场景下的需求，例如在生成文档、进行类型转换或动态代码生成时。

以上就是深度解析：如何在Python中递归剥离typing.Annotated类型注解的详细内容，更多请关注其它相关文章！

# 将其 # 怎么做排名网站推广工作 # 潼南区网站建设推广 # 营销推广短信范例范文 # 湖南网站建设哪家专业 # 上海网站建设售后保障 # 汤阴附近网站建设工程 # seo1 c m # seo推广哪家正规 # seo专员属于什么岗位 # 武汉竞价seo推广 # 不含 # python # 但在 # 子类 # 第一个 # 是在 # 是一个 # 遍历 # 递归 # 递归函数 # ai # 工具 # 正则表达式