如何在Python TypedDict中实现二选一且互斥的字段定义？

你需要处理两种输入数据格式：

• 云端文本文件：

  {"cloud_url": "https://example.com/file.txt", "filetype": "txt"}
  

• 本地CSV文件：

  {"local_filepath": "./file.csv", "filetype": "csv", "delimeter": ","}
  

原有的类型注解尝试通过继承联合类型来实现“二选一”，但TypedDict类无法继承Union类型，导致报错。以下是正确的实现方案：

方案：拆分互斥类型后用Union组合 #

核心思路是将本地/云端路径与文件类型拆分为独立的基础TypedDict，再组合出所有合法的互斥类型，最后用Union汇总。

from typing import Literal, TypedDict, Union

# 定义基础的路径类型，每个类型只包含一个必选路径字段
class _LocalFile(TypedDict):
    local_filepath: str

class _CloudFile(TypedDict):
    cloud_url: str

# 组合文本文件的两种合法类型
class _TxtLocal(_LocalFile):
    filetype: Literal['txt']

class _TxtCloud(_CloudFile):
    filetype: Literal['txt']

# 组合CSV文件的两种合法类型
class _CsvLocal(_LocalFile):
    filetype: Literal['csv']
    delimeter: str

class _CsvCloud(_CloudFile):
    filetype: Literal['csv']
    delimeter: str

# 最终的联合类型，覆盖所有合法输入场景
FileProcess = Union[_TxtLocal, _TxtCloud, _CsvLocal, _CsvCloud]

方案有效性说明 #

1. 每个子类型都继承自单一的TypedDict（_LocalFile或_CloudFile），符合TypedDict的继承规则；
2. 每个子类型只包含一个路径字段，静态类型检查器（如mypy、pyright）会自动识别：
   • 缺少路径字段 → 类型不匹配；
   • 同时包含两个路径字段 → 无法匹配任何子类型，触发类型错误；
3. 通过Literal['txt']和Literal['csv']绑定了文件类型与对应字段（比如CSV必须带delimeter），确保格式合法性。

补充：简化写法（Python 3.11+） #

如果不想定义过多子类，可以直接在Union中内联定义TypedDict：

from typing import Literal, TypedDict, Union

FileProcess = Union[
    TypedDict('TxtLocal', {'local_filepath': str, 'filetype': Literal['txt']}),
    TypedDict('TxtCloud', {'cloud_url': str, 'filetype': Literal['txt']}),
    TypedDict('CsvLocal', {'local_filepath': str, 'filetype': Literal['csv'], 'delimeter': str}),
    TypedDict('CsvCloud', {'cloud_url': str, 'filetype': Literal['csv'], 'delimeter': str}),
]

这种写法更紧凑，但可读性略低于拆分子类的方式，可根据场景选择。

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