Python定义多层嵌套字典类型时遭遇类型兼容错误

需求场景 #

需要定义一个支持如下结构的嵌套字典类型NestedRecord，字典键为字符串，值可以是：

• 字符串、数字（int/float）、布尔值
• 上述基础类型的列表
• 同类型的嵌套字典
• 同类型嵌套字典的列表

示例结构：

test: NestedRecord = {
    "one": "one",
    "two": 2,
    "three": True,
    "four": [1, 2, 3],
    "five": ["one", "two", "three"],
    "another": {
        "one": {"one": ["one"]},
    },
    "six": [{"one": "one"}],
    "seven": [{"one": "one"}, {"two": 2, "three": True}],
    "eight": [{"one": "one"}, {"two": 2, "three": True, "four": {"one": "one"}}],
}

原代码问题 #

最初的类型定义如下，但在six及后续包含字典列表的条目处报错：

from typing import Dict, List, Union

ValidTypes = Union[str, bool, int, float]
ValidLists = Union[List[str], List[bool], List[int], List[float]]

NestedRecord = Dict[
    str, Union[ValidTypes, ValidLists, "NestedRecord", List["NestedRecord"]]
]

错误信息：

Dict entry 6 has incompatible type "str": "list[dict[str, str]]"; expected "str": "str | int | float | list[str] | list[bool] | list[int] | list[float] | NestedRecord | list[NestedRecord]"

问题根源：ValidLists只包含基础类型的列表，而List["NestedRecord"]要求列表元素必须是完整的NestedRecord，但类型检查器无法直接识别[{"one": "one"}]这类符合NestedRecord的结构——核心问题是没有用一个统一的类型来涵盖所有合法的嵌套值，包括任意合法值组成的列表。

正确的类型定义 #

重新调整类型结构，先定义所有合法的嵌套值类型，再基于它定义NestedRecord：

from typing import Dict, List, Union

NestedValue = Union[
    str,
    bool,
    int,
    float,
    List["NestedValue"],
    "NestedRecord"
]

NestedRecord = Dict[str, NestedValue]

这样定义的优势：

• NestedValue一次性涵盖了所有合法值：基础类型、任意合法值的列表、嵌套字典本身
• NestedRecord直接基于NestedValue，自动支持所有嵌套场景，包括字典列表、混合类型列表等
• 类型检查器能正确识别six、seven、eight这类包含字典列表的结构，示例代码可以正常通过类型检查

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