当在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，行为符合预期。
通过这种递归遍历和替换的方法，我们可以有效地管理和利用typing.Annotated的强大功能，同时又能根据需要获取纯净的类型表示，极大地增强了Python类型提示的灵活性和实用性。