Python如何为固定嵌套结构返回值定义复杂类型注解

固定长度元组、嵌套字典/列表的结构可以通过Python泛型类型注解完成约束，不同Python版本写法略有区别：

Python 3.9及以上版本写法 #

3.9版本开始Python内置的tuple/dict/list原生支持泛型标注，固定长度为2的元组需要逐个声明两个位置的元素类型，写法如下：

def get_items() -> tuple[dict[str, list[str]], dict[str, list[str]]]:
    raise NotImplementedError

该注解可以覆盖以下结构约束：

• 返回值为长度固定2的元组，两个位置的元素均为字典
• 字典的键为字符串类型，值为字符串元素构成的列表

Python 3.8及以下版本写法 #

低版本需要从typing模块导入对应泛型类型：

from typing import Tuple, Dict, List

def get_items() -> Tuple[Dict[str, List[str]], Dict[str, List[str]]]:
    raise NotImplementedError

列表长度1/2的约束补充 #

注意：标准Python类型注解默认无法静态约束可变列表list的长度，上述写法只能约束列表内元素为字符串，无法限制长度只能是1或2，可根据需求选择适配方案：

• 如果不需要做静态长度校验，只需要在方法注释中补充值列表的长度要求即可，也可以在抽象基类中增加运行时校验逻辑，子类调用get_items时自动校验返回值结构。
• 如果允许将返回值字典里的列表改为不可变元组（适合返回的序列不需要修改的场景），可以通过联合类型严格约束长度为1或2，Python 3.10+写法示例：

from typing import TypeAlias

# 定义值的类型：长度1的字符串元组，或长度2的字符串元组
ItemValue: TypeAlias = tuple[str] | tuple[str, str]

def get_items() -> tuple[dict[str, ItemValue], dict[str, ItemValue]]:
    raise NotImplementedError

3.10以下版本可以将|替换为Union[tuple[str], tuple[str, str]]，提前从typing模块导入Union即可使用。

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