如何为通用嵌套TypedDict添加类型注解？

一、替代Any的可行方案 #

方案1：使用Protocol定义结构约束 #

通过Protocol定义nested字段必须满足的最小结构（比如包含foo字段），所有符合该结构的TypedDict（无论是否有额外字段）都能被兼容，完美替代Any：

from typing import TypedDict, Protocol

# 定义协议：要求包含foo字段
class HasFooProtocol(Protocol):
    foo: str

class NestedDict(TypedDict):
    foo: str

# 带额外字段的TypedDict示例
class ExtendedNestedDict(TypedDict):
    foo: str
    bar: int

class EventDict(TypedDict):
    nested: NestedDict

class ExtendedEventDict(TypedDict):
    nested: ExtendedNestedDict

# BaseEventDict的nested字段使用协议类型
class BaseEventDict(TypedDict):
    nested: HasFooProtocol

test_dict: EventDict = {"nested": {"foo": "abc"}}
extended_test_dict: ExtendedEventDict = {"nested": {"foo": "def", "bar": 123}}

def print_dict(source_dict: BaseEventDict):
    print(source_dict)

# 两种类型都能通过mypy检查
print_dict(test_dict)
print_dict(extended_test_dict)

方案2：使用泛型TypedDict（Python 3.10+） #

如果需要更严格的类型绑定，可以用泛型TypeVar限定TypedDict类型：

from typing import TypedDict, TypeVar, Generic

# 定义绑定到TypedDict的类型变量
T = TypeVar('T', bound=TypedDict)

class BaseEventDict(Generic[T], TypedDict):
    nested: T

class NestedDict(TypedDict):
    foo: str

class ExtendedNestedDict(TypedDict):
    foo: str
    bar: int

class EventDict(TypedDict):
    nested: NestedDict

def print_dict[T](source_dict: BaseEventDict[T]):
    print(source_dict)

test_dict: EventDict = {"nested": {"foo": "abc"}}
print_dict(test_dict)  # 类型检查通过

二、为什么Mapping[str, object]在此处无效 #

PEP 0589提到的「任何TypedDict类型与Mapping[str, object]一致」仅指运行时行为——TypedDict在运行时本质就是普通字典，因此和Mapping[str, object]的运行时表现一致。但在**静态类型检查（如mypy）**中：

• TypedDict是一种结构类型，它对键的集合和对应值的类型有严格约束（默认要求所有键必须存在）；
• Mapping[str, object]是泛型映射类型，属于更宽泛的类型范畴；
• mypy不会自动将TypedDict类型隐式转换为Mapping[str, object]，因为TypedDict携带了更具体的结构信息，mypy认为二者属于不同的类型层级，因此会报类型不兼容错误。

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