如何为含必填键与任意可选键的Python字典添加类型提示？

Python 3.11及以上版本可以通过TypedDict的__extra_items__属性实现类似TypeScript的「必填键+任意同类型额外键」的类型提示，低版本则可以用Protocol来模拟。

一、Python 3.11+ 推荐方案：TypedDict + extra_items #

直接定义TypedDict类，指定必填键后，用__extra_items__声明额外键的类型（搭配NotRequired表示额外键可选）：

from typing import TypedDict, NotRequired

class Family(TypedDict):
    # 必填键，必须存在且为str类型
    father: str
    mother: str
    # 任意额外的字符串键，对应的值为str类型，可选存在
    __extra_items__: NotRequired[str]

类型检查工具（如mypy、pyright）会识别以下约束：

• 必须包含father和mother两个键，类型为str
• 允许添加任意其他字符串类型的键，对应的值也必须是str
• 额外键无需预先声明具体名称，完全灵活

使用示例：

# 符合类型要求
valid_family: Family = {
    "father": "John",
    "mother": "Mary",
    "son1": "Tom",
    "daughter1": "Lily"
}

# 缺少必填键，触发类型错误
invalid_family: Family = {
    "father": "John"
}

# 额外键类型错误，触发类型错误
invalid_family_2: Family = {
    "father": "John",
    "mother": "Mary",
    "son1": 123  # 类型应为str
}

二、Python 3.10及以下：用Protocol模拟 #

如果项目仍使用Python 3.10或更低版本，可以通过Protocol定义协议类，既保证必填键存在，又支持任意额外字符串键：

from typing import Protocol

class FamilyProtocol(Protocol):
    # 声明必填属性，类型为str
    father: str
    mother: str

    # 声明任意字符串键的取值类型为str
    def __getitem__(self, key: str) -> str: ...

使用时直接用FamilyProtocol作为类型提示：

def print_family(family: FamilyProtocol) -> None:
    print(f"Father: {family['father']}, Mother: {family['mother']}")
    # 可安全访问额外键
    if "son1" in family:
        print(f"Son1: {family['son1']}")

# 符合要求的字典
valid_family = {
    "father": "John",
    "mother": "Mary",
    "daughter1": "Lily"
}
print_family(valid_family)

这种方式通过Protocol约束「必须包含father和mother属性，同时支持以字符串为键获取str类型值」，类型检查工具会认可符合该约束的字典。

补充说明 #

• TypedDict的total=False参数是让所有键变为可选，并非允许额外键，不符合需求；NotRequired仅适用于预先声明的可选键，无法覆盖未知的额外键。
• __extra_items__是Python 3.11为TypedDict新增的特性，专门用来处理「任意额外键」场景，完全对应TypeScript中的索引签名语法。

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