如何在Python中为TypedDict指定多个重载类型？

在开发Minecraft模组下载安装程序时，我需要为MediaList字典做类型约束：不同的type值对应不同的必填字段（比如type="cf"时必须有id，type="url"时必须有link）。尝试过重复定义MediaList类或者用total=False的方式，但要么不生效，要么访问字段时会触发类型错误提示。

正确实现方案 #

要实现这种“按类型分支”的TypedDict约束，正确的做法是用多个TypedDict子类对应不同type场景，再通过Union组合成最终类型，同时抽公共字段到父类减少重复代码。

完整代码示例

from typing import Literal, TypedDict, Union

# 公共字段：所有类型都包含的必填字段，加上可选的sides（仅部分类型会有）
class BaseMediaList(TypedDict, total=False):
    sides: list[Literal['client', 'server']]

class CFMediaList(BaseMediaList):
    type: Literal['cf']
    slug: str
    name: str
    id: int  # cf类型专属必填字段

class PMMediaList(BaseMediaList):
    type: Literal['pm']
    slug: str
    name: str
    media: str  # pm类型专属必填字段

class MRMediaList(BaseMediaList):
    type: Literal['mr']
    slug: str
    name: str
    id: str  # mr类型的id为字符串，注意和cf区分

class URLMediaList(BaseMediaList):
    type: Literal['url']
    slug: str
    name: str
    link: str  # url类型专属必填字段

# 最终的MediaList类型是上述子类的联合类型
MediaList = Union[CFMediaList, PMMediaList, MRMediaList, URLMediaList]

效果说明

• 类型检查器会自动识别不同type对应的专属字段：比如判断media['type'] == 'cf'后，访问media['id']不会再触发“字段可能不存在”的类型错误
• 每个子类的必填字段会被严格校验：创建CFMediaList时漏掉id会直接触发类型提示
• 公共字段slug、name在所有类型中强制必填，sides作为可选字段仅部分类型会用到

为什么之前的写法无效？ #

1. 重复定义MediaList类：Python中后定义的类会覆盖前一个，类型检查器只会识别最后一个定义的类，无法实现分支约束
2. 使用total=False：会把所有额外字段标记为可选，无法区分“某个type下必须存在”的字段，导致访问时编辑器提示风险

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