解析类型字符串以提取泛型参数（如 Tuple 中的子类型）

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

在 Python 类型注解的实际应用中，我们常需动态解析类型字符串（例如从文档、配置或反射中获取的 str 形式类型），尤其是处理 Tuple[T1, T2, ...] 这类带泛型参数的构造。但若依赖正则表达式匹配方括号内容，极易在遇到嵌套类型（如 Union[A, Tuple[B, C]]）或含逗号的字符串字面量时出错——因为正则无法理解语法层级与括号配对关系。

更健壮的方案是利用 Python 内置的抽象语法树（AST）解析器：ast.parse(..., mode="eval") 可将类型字符串视为合法的 Python 表达式进行解析，从而精准定位泛型参数节点，无需手动平衡括号或处理转义。

以下是一个生产就绪的解析函数，支持单元素与多元素 Tuple[...] 场景，并统一返回 list[str]（单元素也包装为长度为 1 的列表，提升调用一致性）：

import ast

def extract_tuple_args(type_str: str) -> list[str]:
    """
    从形如 'Tuple[A, B]' 或 'Tuple[Union[X, Y], List[Z]]' 的字符串中，
    提取方括号内的各类型参数（保持原始字符串格式）。

    Args:
        type_str: 合法的 Python 类型提示字符串，必须以 'Tuple[' 开头

    Returns:
        list[str]: 每个元素为一个原始类型参数子串（不含外层括号）

    Raises:
        ValueError: 当输入非 Tuple subscript 表达式或语法无效时
    """
    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 Tuple subscript expression, got {type(node.body).__name__}: {type_str!r}")

    # 确保基类为 'Tuple'（可选增强：校
验 id 为 'Tuple'）
    if not isinstance(node.body.value, ast.Name) or node.body.value.id != "Tuple":
        raise ValueError(f"Expected 'Tuple[...]', but got {ast.unparse(node.body.value)}[...]")

    slice_node = node.body.slice
    lines = type_str.splitlines()

    if isinstance(slice_node, ast.Tuple):
        # 多参数：Tuple[A, B, C]
        return [
            lines[e.lineno - 1][e.col_offset : e.end_col_offset].strip()
            for e in slice_node.elts
        ]
    else:
        # 单参数：Tuple[A] → 返回 [A]
        return [lines[slice_node.lineno - 1][slice_node.col_offset : slice_node.end_col_offset].strip()]

✅ 使用示例：

# 基础用例
assert extract_tuple_args("Tuple[int, str]") == ["int", "str"]
assert extract_tuple_args("Tuple[int]") == ["int"]

# 复杂嵌套（正则易失败的场景）
s = "Tuple[Union[file.File, directory.Directory, Tuple[file.File, directory.Directory]], Tuple[file.File, directory.Directory]]"
result = extract_tuple_args(s)
assert result == [
    "Union[file.File, directory.Directory, Tuple[file.File, directory.Directory]]",
    "Tuple[file.File, directory.Directory]"
]

⚠️ 注意事项：

• 该方法依赖 ast.parse，因此输入必须是语法合法的 Python 表达式（如不能含未定义名称、非法符号）；
• 不校验类型是否存在或是否有效（如 file.File 是否真实导入），仅做结构解析；
• 若需支持 tuple[...]（PEP 646 引入的内置泛型别名），可扩展判断逻辑（检查 ast.Name(id='tuple')）；
• 对于极端场景（如含注释、多行换行符干扰 lineno/col_offset），建议先标准化输入（如 ast.unparse(ast.parse(...)) 生成规范形式再解析）。

总之，借助 ast 模块解析类型字符串，既规避了正则的脆弱性，又无需引入第三方依赖，是处理 Python 类型提示文本解析的推荐实践。