Python中如何定义递归类型提示？解决递归字典类型别名报错问题

问题描述 #

我定义了一个类型别名，希望支持任意层级的嵌套字典：

from typing import Tuple, Dict, Union

SelectedModelArgs = Dict[
    str,
    Union[
        str,
        float,
        Tuple[float, float],
        SelectedModelArgs,
    ],
]

但遇到以下错误：

• Pylance："SelectedModelArgs" is not defined
• Mypy：Cannot resolve now "SelectedModelArgs" (possible cyclic definition)
  添加from __future__ import annotations仅部分解决问题，将嵌套的SelectedModelArgs改为字符串形式只能修复Pylance错误，Mypy的报错依旧存在。

解决方案 #

方法1：使用typing.TypeAlias（Python 3.10+） #

结合from __future__ import annotations，用TypeAlias明确声明类型别名，同时用字符串引用自身：

from __future__ import annotations
from typing import Tuple, Dict, Union, TypeAlias

SelectedModelArgs: TypeAlias = Dict[
    str,
    Union[
        str,
        float,
        Tuple[float, float],
        "SelectedModelArgs",
    ],
]

这种方式能同时兼容Pylance和Mypy：TypeAlias明确告诉类型检查器这是一个类型别名，字符串引用避免了定义时的循环解析问题。

方法2：使用PEP 604联合类型语法（Python 3.10+） #

可以用|简化Union的写法，同时保持字符串引用自身：

from __future__ import annotations
from typing import Tuple, Dict, TypeAlias

SelectedModelArgs: TypeAlias = Dict[
    str,
    str | float | Tuple[float, float] | "SelectedModelArgs",
]

方法3：兼容旧Python版本（使用typing_extensions） #

如果Python版本低于3.10，先安装typing_extensions库：

pip install typing-extensions

再编写代码：

from __future__ import annotations
from typing import Tuple, Dict, Union
from typing_extensions import TypeAlias

SelectedModelArgs: TypeAlias = Dict[
    str,
    Union[
        str,
        float,
        Tuple[float, float],
        "SelectedModelArgs",
    ],
]

关键说明 #

• from __future__ import annotations会让所有类型注解以字符串形式存储，延迟解析，避免定义时的循环问题。
• 用TypeAlias显式声明类型别名，能让类型检查器更准确识别，解决Mypy的循环定义报错。
• 字符串形式的"SelectedModelArgs"是递归类型的标准写法，确保类型检查器在后续解析时能正确识别。

内容的提问来源于stack exchange，提问作者ChrisProsser