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

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

在 Python 类型提示的实际应用中，我们常需动态解析类似 "Tuple[int, Union[str, float]]" 这样的字符串，从中提取每个泛型参数（即方括号内的逗号分隔项）。由于类型嵌套（如 Union[...]、Tuple[...]、Optional[...]）的存在，单纯依赖正则表达式极易出错——它无法正确匹配嵌套括号的边界，导致截断或越界。

更健壮的方案是利用 Python 自带的抽象语法树（AST）解析器：ast.parse(..., mode="eval") 可将类型字符串作为合法表达式安全解析（不执行），再通过遍历 AST 节点精准定位泛型参数的位置与内容。

以下是一个生产就绪的解析函数：

import ast

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

    支持任意嵌套（如 Union[Tuple[X, Y], Z]），返回原始字符串片段（非运行时类型对象）。
    返回 list[str] 表示多参数；单参数时返回 str（保持语义清晰，避免歧义）。
    """
    try:
        tree = 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(tree.body, ast.Subscript):
        raise ValueError(f"Expected subscript expression (e.g., 'Tuple[...]'), got {type(tree.body).__name__}")

    slice_node = tree.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()

✅ 使用示例：

# 基础用法
print(extract_tuple_hints("Tuple[int, str]"))
# → ['int', 'str']

# 单参数元组
print(extract_tup
le_hints("Tuple[bool]"))
# → 'bool'

# 复杂嵌套（完美支持）
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]'
#    ]

⚠️ 注意事项：

• 该函数仅解析字符串结构，不导入或求值任何模块（如 file.File 不会被导入），因此安全可靠；
• 返回的是原始字符串切片，保留了源字符串中的空格、换行和注释（如有），如需进一步类型化，可配合 typing.get_origin / get_args（需 eval + globals，慎用）；
• 若需统一返回 list[str]（含单元素），可将末尾 else 分支改为 [...single...]；
• 不支持带关键字参数的类型（如 Tuple[int, ...] 中的 Ellipsis 需额外处理，但本例未涉及）。

总结：面对嵌套类型字符串的解析需求，ast 是标准、轻量且语义准确的首选工具。它规避了正则的脆弱性，无需引入第三方依赖，同时为后续扩展（如校验合法性、转换为 TypeVar 等）提供了坚实基础。