Python类型注解：运行时高效剥离Annotated获取纯净裸类型-Python教程-PHP中文网

Python类型注解：运行时高效剥离Annotated获取纯净裸类型

DDD

发布： 2025-11-05 11:43:00

原创

602人浏览过

Python类型注解：运行时高效剥离Annotated获取纯净裸类型

当在python中使用`typing.annotated`时，复杂的类型提示可能会因元数据而变得冗长。本教程旨在解决如何从深度嵌套的`annotated`结构中提取底层“裸”类型，而不改变原始定义。我们将介绍一个强大的递归函数，它能在运行时遍历类型提示树，有效剥离`annotated`包装器，从而得到一个干净、无注解的类型表示，这对于需要纯粹类型内省的场景至关重要。

理解typing.Annotated及其挑战

typing.Annotated是Python 3.9引入的一个强大工具，它允许开发者在类型提示中添加上下文特定的元数据，而不会影响类型检查器对基础类型的处理。例如，我们可以定义一个带有描述的3D点类型：

from typing import Annotated, tuple, list

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

登录后复制

然而，当我们需要获取这些类型的“纯净”表示时，Annotated及其元数据可能会带来困扰。直接打印Points会显示所有嵌套的注解：

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

登录后复制

在某些场景下，例如生成API文档、进行运行时类型检查或序列化时，我们可能只需要list[tuple[float, float, float]]这样的裸类型，而不需要任何注解信息。

为什么简单的get_args不足以解决问题

typing模块提供了get_args函数，用于获取泛型类型的参数。尝试使用get_args(Points)[0]可以移除最外层的Annotated，但它无法深入处理嵌套的Annotated：

立即学习“Python免费学习笔记（深入）”；

# 假设 Points = Annotated[list[Annotated[tuple[float, float, float], 'A 3D Point']], 'A collection of points']
# get_args(Points)[0] 结果会是：
# list[typing.Annotated[tuple[float, float, float], 'A 3D Point']]

登录后复制

正如所见，内部的'A 3D Point'注解依然存在，这表明我们需要一种更全面的方法来递归地剥离所有注解。

递归剥离Annotated的解决方案

解决此问题的关键在于递归地遍历类型提示的结构（可以将其视为一个类型树），并在遇到Annotated节点时，将其替换为其基础类型（即Annotated的第一个参数）。typing模块中的get_origin和get_args函数是实现这一遍历的基石。

千帆大模型平台

面向企业开发者的一站式大模型开发及服务运行平台

查看详情

get_origin(type_object): 返回泛型类型（如list[int]）的原始类型（如list）。对于非泛型类型，返回None。
get_args(type_object): 返回泛型类型的所有类型参数（如list[int]的int）。

下面是实现这一功能的递归函数：

from typing import Annotated, get_args, get_origin, Any

def convert_annotated_to_bare_types(type_object: Any) -> Any:
  """
  递归地将类型提示中的所有 typing.Annotated 包装器替换为其基础类型。

  参数:
    type_object: 待处理的类型对象。

  返回:
    移除了所有 Annotated 包装器的纯净类型对象。
  """
  # 获取类型对象的原始类型（如 list[int] 的 list）和参数（如 int）
  origin, args = get_origin(type_object), get_args(type_object)

  # 情况1: 如果没有原始类型，说明这不是一个泛型类型（如 int, str, float）
  # 或者是一个普通的非泛型类。直接返回它本身。
  if origin is None:
    return type_object

  # 情况2: 如果原始类型是 Annotated，说明我们遇到了一个注解类型。
  # Annotated 的第一个参数是其基础类型，我们递归处理这个基础类型。
  if origin is Annotated:
    bare_type = get_args(type_object)[0] # 获取 Annotated 的第一个参数（即裸类型）
    return convert_annotated_to_bare_types(bare_type)

  # 情况3: 如果是其他泛型类型（如 list, dict, Union, Optional 等）
  # 我们需要递归处理它的所有类型参数。
  converted_args = [
    convert_annotated_to_bare_types(arg) for arg in args
  ]

  # 使用原始类型和处理后的参数重新构造泛型类型。
  # 例如，list[*converted_args] 会重构为 list[处理后的参数]
  return origin[*converted_args]

登录后复制

示例与应用

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

# 重新定义示例类型
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(f"原始类型: {Points}")
print(f"转换后的裸类型: {bare_points_type}")

登录后复制

输出结果将是：

原始类型: typing.Annotated[list[typing.Annotated[tuple[float, float, float], 'A 3D Point']], 'A collection of points']
转换后的裸类型: list[tuple[float, float, float]]

登录后复制

这正是我们期望的结果，所有嵌套的Annotated及其元数据都被成功移除了。

注意事项与总结

运行时操作: convert_annotated_to_bare_types是一个运行时函数，它在程序执行时检查并转换类型对象。它不会修改源代码或类型检查器的行为。
不改变原始定义: 此函数是纯粹的，它返回一个新的类型对象，而不会改变传入的原始Annotated类型定义。这意味着你仍然可以在需要元数据的地方使用原始的Annotated类型。
适用场景:
- API文档生成: 当你希望在文档中显示简洁的类型签名，而不包含内部注解元数据时。
- 数据验证/序列化: 在需要根据纯粹的类型结构进行数据验证或序列化（如Pydantic模型）时，可以先剥离注解。
- 自定义类型检查: 当构建自己的运行时类型检查工具，且需要忽略Annotated元数据时。
Any类型处理: 对于Any类型，get_origin返回None，get_args返回()，函数会直接返回Any，行为符合预期。