解析 Python 类型注解字符串以提取泛型参数（如 Tuple 中的子类型）_技术教程

本文介绍如何安全、准确地从类型注解字符串（如 `"tuple[int, union[str, list]]"`）中提取泛型参数，避免正则表达式在嵌套结构中的失效问题，推荐使用标准库 `ast` 模块进行语法树解析。

在 Python 类型提示（type hinting）的实际应用中，我们常需动态解析类型字符串（例如从配置、文档或序列化数据中读取的 Tuple[...]、List[...] 等），并提取其内部的类型参数。但这类字符串具有嵌套性——如 Union[A, Tuple[B, C]] 中方括号可多层嵌套，传统正则表达式极易因无法匹配括号平衡而失败。

此时，最稳健的方式是借助 Python 内置的抽象语法树（AST）解析器：ast.parse(..., mode="eval") 可将合法的类型表达式（符合 Python 表达式语法）安全地构造成语法树，无需执行代码，也无注入风险。

以下是一个生产就绪的解析函数，专用于提取 Tuple[...] 类型中的各项子类型：

import ast

def extract_tuple_hints(type_str: str) -> list[str] | str:
    """
    从形如 'Tuple[A, B]' 或 'Tuple[A]' 的类型字符串中提取泛型参数子串。

    返回：
      - 若含多个参数（如 Tuple[A, B]）→ list[str]，每个元素为原始字符串中的子类型片段；
      - 若仅一个参数（如 Tuple[A]）→ str，即该子类型原始表示。
    """
    try:
        node = ast.parse(type_str.strip(), mode="eval")
    except SyntaxError as e:
        raise ValueError(f"Invalid type string syntax: {type_str!r}") from e

    if not isinstance(node.body, ast.Subscript):
        raise ValueError(f"Expected subscript expression (e.g., 'Tuple[...]'), got {type(node.body).__name__}")

    # 获取目标 Subscript 节点的 slice（即 [...] 中的内容）
    slice_node = node.body.slice

    # 拆分逻辑：根据 slice 是 ast.Tuple 还是单个表达式处理
    if isinstance(slice_node, ast.Tuple):
        # 多参数：Tuple[A, B, C]
        lines = type_str.splitlines()
        return [
            lines[e.lineno - 1][e.col_offset : e.end_col_offset].strip()
            for e in slice_node.elts
        ]
    else:
        # 单参数：Tuple[A] → 直接提取 slice 区域
        lines = type_str.splitlines()
        return lines[slice_node.lineno - 1][slice_node.col_offset : slice_node.end_col_offset].strip()

✅ 使用示例：

# 多参数嵌套场景（正则难以处理）
s = "Tuple[Union[file.File, directory.Directory, Tuple[file.File, directory.Directory]], Tuple[file.File, directory.Directory]]"
print(extract_tuple_hints(s))
# 输出：
# ['Union[file.File, directory.Directory, Tuple[file.File, directory.Directory]]',
#  'Tuple[file.File, directory.Directory]']

# 单参数与基础类型
print(extract_tuple_hints("Tuple[int]"))      # 'int'
print(extract_tuple_hints("Tuple[int, str]")) # ['int', 'str']

⚠️ 注意事项：

输入字符串必须是语法合法的 Python 表达式（如不能含未加引号的 None、True 等字面量，除非明确作为类型名；推荐统一使用字符串形式或确保上下文已定义）；
该方法不执行任何代码，纯静态解析，安全可靠；
若需支持更广类型（如 List[...]、Optional[
...]），只需扩展对 node.body.value.id 的校验（如检查是否为 "List"），核心解析逻辑复用；
返回的是原始字符串切片，如需进一步转为实际 type 对象，应配合 typing.get_args() + eval()（需严格信任输入）或 typing.ForwardRef + typing.eval_type()（Python 3.10+ 推荐）。