如何让mypy识别dataclass通过__post_init__转换的初始化参数类型？

方案1：使用联合类型 + 类型断言/运行时验证 #

给字段设置Union[list[tuple[str, str]], dict[str, str]]类型，让mypy认可两种初始化输入，再在__post_init__中完成类型转换，通过类型断言或assert语句消除mypy的类型报错。

from dataclasses import dataclass
from typing import Union, cast

@dataclass
class Foobar:
    items: Union[list[tuple[str, str]], dict[str, str]] = []

    def __post_init__(self) -> None:
        if isinstance(self.items, dict):
            # 把dict转为目标类型，用cast告知mypy转换后的类型正确性
            self.items = cast(list[tuple[str, str]], list(self.items.items()))
        # 可选：用assert进一步明确类型，同时在运行时验证数据合法性
        assert isinstance(self.items, list)
        assert all(isinstance(item, tuple) and len(item) == 2 and isinstance(item[0], str) and isinstance(item[1], str) for item in self.items)

说明 #

• 联合类型让dataclass自动生成的__init__直接接受两种参数类型，无需重写构造函数。
• cast仅作用于类型检查阶段，不会改变运行时行为，但能让mypy信任我们的类型转换逻辑。
• 后续的assert语句既可以让mypy明确items的最终类型，也能在运行时确保数据符合预期。

方案2：私有存储字段 + 公共属性隔离 #

用私有字段存储最终的list[tuple[str, str]]数据，用联合类型的公共字段处理初始化输入，在__post_init__完成转换后隐藏输入字段，对外暴露类型正确的属性。

from dataclasses import dataclass, field
from typing import list, tuple, dict, Union

@dataclass
class Foobar:
    # 私有字段，存储最终的正确类型数据，不参与初始化
    _items: list[tuple[str, str]] = field(default_factory=list, init=False)
    # 公共初始化字段，支持两种类型输入
    items: Union[list[tuple[str, str]], dict[str, str]] = field(default_factory=list)

    def __post_init__(self) -> None:
        # 转换输入数据到私有字段
        if isinstance(self.items, dict):
            self._items = list(self.items.items())
        else:
            self._items = self.items
        # 删除初始化用的字段，避免对外暴露联合类型
        del self.items

    # 对外暴露类型严格的属性
    @property
    def items(self) -> list[tuple[str, str]]:
        return self._items

说明 #

• 对外暴露的items始终是list[tuple[str, str]]类型，mypy不会有任何类型疑虑。
• 初始化时完全兼容两种参数类型，不需要修改自动生成的__init__。
• 缺点是需要额外定义私有字段和属性，代码结构稍复杂。

内容的提问来源于stack exchange，提问作者Nico Schlömer