本文探讨了如何在运行时从 `typing.Annotated` 类型中递归地移除注解信息，以获取其纯净的基础类型表示。通过介绍一个基于 `typing.get_origin` 和 `typing.get_args` 的递归函数，我们展示了如何遍历复杂的嵌套类型结构，将所有 `Annotated` 节点替换为其裸类型，从而实现类型表示的净化，避免了冗余注解在特定场景下的显示。
在 python 的类型提示系统中，typing.Annotated 提供了一种强大的机制，允许开发者为类型添加额外的元数据（如描述、验证规则等），而这些元数据在运行时是可访问的。这对于构建依赖注入框架、API 文档生成或复杂数据验证等场景非常有用。然而，当这些带有注解的类型被嵌套使用时，它们的字符串表示可能会变得冗长且难以阅读，尤其是在需要打印或调试纯净类型结构时。
考虑以下类型别名：
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 会得到一个包含所有注解信息的复杂字符串：
立即学习“Python免费学习笔记（深入）”；
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 类型
要解决这个问题，我们需要在运行时遍历整个类型结构，识别并处理所有的 Annotated 节点。Python 的 typing 模块提供了 get_origin 和 get_args 这两个函数，它们是解析泛型类型结构的关键工具。
- typing.get_origin(type_object): 对于泛型类型（如 list[int]），它返回泛型类型本身（list）。对于非泛型类型或没有参数的类型，它返回 None。
- typing.get_args(type_object): 对于泛型类型（如 list[int]），它返回一个包含所有类型参数的元组（(int,)）。对于非泛型类型，它返回一个空元组 ()。
利用这两个函数，我们可以构建一个递归函数来“净化”类型对象，即将其中的所有 Annotated 节点替换为其基础类型。
实现类型净化函数
以下是实现这一功能的 Python 函数：
from typing import Annotated, get_args, get_origin, Union def convert_annotated_to_bare_types(type_object: type): """ 递归地将类型对象中所有 `typing.Annotated` 节点转换为其纯净的基础类型。 Args: type_object: 待处理的类型对象。 Returns: 移除了所有 `Annotated` 注解的纯净类型对象。 """ origin, args = get_origin(type_object), get_args(type_object) # 1. 基本情况：如果类型没有 origin (即不是泛型或没有参数)，则直接返回。 # 例如：int, float, str 等。 if origin is None: return type_object # 2. 处理 Annotated 类型： # 如果 origin 是 Annotated，我们只关心它的第一个参数（即实际的类型）。 # 对这个实际类型递归调用本函数，以处理其内部可能存在的嵌套 Annotated。 if origin is Annotated: bare_type = get_args(type_object)[0] return convert_annotated_to_bare_types(bare_type) # 3. 处理其他泛型类型（如 list, dict, Union 等）： # 对所有类型参数递归调用本函数，以净化它们。 # 然后使用 origin 和净化后的参数重建泛型类型。 converted_args = [ convert_annotated_to_bare_types(arg) for arg in args ] # 特殊处理 Union 类型，因为 Union[*args] 语法在 Python 3.9+ 才能使用 # 对于旧版本，可能需要 Union[arg1, arg2] if origin is Union: # Union[X, Y] 等同于 X | Y if not converted_args: return type(None) # Union without args is effectively None if len(converted_args) == 1: return converted_args[0] # Python 3.9+ 推荐使用 X | Y 语法，但为了兼容性，Union[*args] 也是可行的 # 这里的 origin[*converted_args] 能够正确处理 Union return origin[*converted_args] # 对于其他泛型类型，直接使用 origin[*converted_args] 重建 return origin[*converted_args]
示例应用
现在，让我们使用这个函数来净化之前定义的 Points 类型：
# 重新定义类型以便运行示例 Point3D = Annotated[tuple[float, float, float], "A 3D Point"] Points = Annotated[list[Point3D | list[float]], "A collection of points"] # 注意这里将 Union 改为 | 语法以更清晰 # 原始的 Points 类型表示 print(f"原始类型: {Points}") # 净化后的类型 cleaned_points_type = convert_annotated_to_bare_types(Points) print(f"净化后类型: {cleaned_points_type}") # 预期输出： # 原始类型: 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 类型定义仍然保留其注解信息，这使得我们可以在其他需要这些元数据的场景下继续使用它们。
- 通用性：该方法不依赖于正则表达式，而是利用 typing 模块提供的标准API来解析类型结构，因此更加健壮和准确，能够处理任意深度的嵌套和复杂的泛型组合。
- 应用场景：此技术适用于需要生成简洁类型表示的场景，例如：
- 动态生成 API 文档时，只显示核心类型结构。
- 在某些数据验证或序列化库中，需要获取不含元数据的基础类型。
- 调试时，获取更清晰的类型输出。
通过这种递归遍历和重构类型对象的方法，我们能够有效地管理 typing.Annotated 带来的类型信息丰富性与类型表示简洁性之间的平衡，确保在不同需求下都能获得最合适的类型视图。