如何在Pydantic数据类中实现字段多类型初始化且保持不可变性？

完全可以实现字段定义为tuple类型，同时让__init__支持list和tuple两种输入，并且通过文档清晰区分两类使用者的行为。

优化后的实现代码 #

针对Pydantic v2版本，调整后的代码如下：

from pydantic import field_validator
from pydantic.dataclasses import dataclass
from typing import List, Union, Tuple

@dataclass(frozen=True)
class MyClass:
    """
    具备不可变字段的数据类示例

    参数
    ---------
    field: Union[List[int], Tuple[int, ...]]
        初始化时可传入整数列表或整数元组；对象实例化后，该字段将始终为**不可变的元组类型**
    """
    field: Tuple[int, ...]

    @field_validator("field", mode="before")
    def convert_to_tuple(cls, value):
        # 将输入的列表转换为元组，保证字段不可变性
        if isinstance(value, list):
            return tuple(value)
        return value

文档字符串的编写要点 #

1. 参数描述区：直接在参数的文档里明确说明两种输入类型，以及最终返回的不可变类型，用**强调读取时的类型特性，让写入者和读取者都能快速get到各自需要的信息。
2. 类描述区：在类的开头说明整体特性，比如这是一个带不可变字段的数据类，帮助使用者快速理解类的定位。
3. 内部注释（可选）：给验证器函数加单行注释，说明它的转换作用，这部分属于内部实现细节，不对外暴露但能帮助维护代码的人理解逻辑。

关键细节说明 #

• 字段的类型注解写为Tuple[int, ...]，明确告诉读取者实例化后该字段的类型是不可变元组；
• 验证器加上mode="before"，确保在Pydantic的类型校验前完成转换，避免传入list时触发类型错误；
• 文档里同时标注输入支持的类型和最终的字段类型，兼顾两类使用者的需求。

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