Python字典未知键名场景下如何注解键与值的类型

针对键名未知、键数量可变、所有键/值类型统一的字典场景，直接使用泛型字典类型注解即可，不需要使用TypedDict——TypedDict仅适配键名固定、每个键对应值类型可独立定义的字典场景。

具体写法 #

根据使用的Python版本选择对应写法：

Python 3.9 及以上版本 #

Python 3.9 开始支持内置泛型类型，直接使用dict[键类型, 值类型]的格式注解即可，完全匹配期望的注解效果，对应需求注解为dict[int, list[int]]：

# 示例：作为返回值的注解
def fetch_id_mapping() -> dict[int, list[int]]:
    # 键可以是任意int，值为任意长度的int列表，键数量无限制
    return {
        101: [2, 7, 9],
        203: [1],
        999: [3, 4, 5, 6, 8]
    }

# 示例：变量注解
id_map: dict[int, list[int]] = {}
id_map[5] = [10, 20]  # 类型校验通过
# id_map["user_1"] = [1,2]  # 类型检查器会报错：键类型不匹配
# id_map[6] = (1,2,3)       # 类型检查器会报错：值类型不是list[int]

这个注解完全覆盖所有规则要求：

• 不需要提前声明具体键名
• 支持任意数量的键
• 强制所有键为int类型
• 强制所有值为list类型
• 不限制值列表的长度
• 强制值列表内的元素为int类型

Python 3.8 及更早版本 #

早期Python版本没有内置泛型支持，需要从typing模块导入对应泛型类型：

from typing import Dict, List

def fetch_id_mapping() -> Dict[int, List[int]]:
    return {1: [1, 2, 3]}

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