如何为完全空字典添加适配TypedDict场景的Python类型提示？

针对你需要的「值要么是完整的TypedDict，要么是完全空的字典」场景，以下是两种满足要求的解决方案：

方案1：用Literal[{}]（推荐，Python 3.10+） #

直接用Literal[{}]表示完全空的字典，完美契合你的两个要求：

• 满足a：类型检查器会明确阻止对任何特定键的读写（因为它知道这是空字典）；
• 满足b：空字典本身符合Mapping[str, float]的约束，能直接传入接受该类型的函数。

示例代码：

from typing import TypedDict, Mapping, Literal, Union

# 你的非简单TypedDict
class FullData(TypedDict):
    id: float
    value: float

# 定义目标类型：要么是完整的FullData，要么是空字典
Data = Union[FullData, Literal[{}]]

def serialize(data: Mapping[str, float]) -> None:
    """接受符合键值类型的任意Mapping（比如序列化到JSON）"""
    pass

def process(data: Data) -> None:
    if data == {}:
        print("执行空字典处理逻辑")
        # 尝试访问data['id']会触发类型错误：Key 'id' not present in Literal[{}]
        # data['id']  # MyPy/PyRight直接报错
    else:
        print(f"处理全量数据：id={data['id']}, value={data['value']}")

# 测试用例
process(FullData(id=1.0, value=2.0))  # 正常运行
process({})  # 正常运行
serialize({})  # 正常，空字典兼容Mapping[str, float]
serialize(FullData(id=1.0, value=2.0))  # 正常

方案2：自定义空TypedDict（兼容旧Python版本） #

如果需要兼容Python 3.10之前的版本，可以通过以下两种方式处理：

2.1 用__extra_items__约束（Python 3.11+） #

利用Python 3.11新增的__extra_items__特性，结合Never类型强制空TypedDict不能包含任何键，同时让它兼容目标Mapping类型：

from typing import TypedDict, Mapping, Never, Union

class EmptyDict(TypedDict):
    __extra_items__: Never  # 禁止任何额外键，只能是空字典

class FullData(TypedDict):
    id: float
    value: float

Data = Union[FullData, EmptyDict]

def serialize(data: Mapping[str, float]) -> None: ...

serialize(EmptyDict())  # 现在能正常通过类型检查

2.2 类型转换绕过检查（兼容更早版本） #

如果无法使用Python 3.11特性，可以用cast做类型转换，让检查器认可空TypedDict与目标Mapping的兼容性：

from typing import TypedDict, Mapping, Union, cast

class EmptyDict(TypedDict):
    pass

class FullData(TypedDict):
    id: float
    value: float

Data = Union[FullData, EmptyDict]

def serialize(data: Mapping[str, float]) -> None: ...

# 使用cast转换类型，通过检查
serialize(cast(Mapping[str, float], EmptyDict()))

为什么空TypedDict会报错？ #

你遇到的类型不兼容问题，本质是空TypedDict的默认值类型是object，而Mapping[str, float]的值类型是float。由于Mapping的类型参数是协变的（_VT_co），object不是float的子类型，所以类型检查器判定两者不兼容。而Literal[{}]或带__extra_items__: Never的TypedDict，检查器能识别出它们的所有值（不存在）都符合float约束，因此可以正常兼容。

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