Python dataclass 与命名元组

dataclass 自动生成样板方法承载数据；namedtuple/TypedDict 提供轻量记录替代。

#concept #growing #dev #python #python

[!info] related notes

所属 MOC：类型与 OOP · 学习路线

前置概念：类与面向对象 · 类型标注

后续概念：JSON

Python dataclass 与命名元组

这个概念为什么出现

大量类只是“一堆字段 + 比较/展示”。手写 __init__/__repr__/__eq__ 易漏。dataclass 用声明生成这些样板；namedtuple 提供不可变记录。

[!abstract] 一句话理解 @dataclass 按字段声明生成初始化与常用方法；namedtuple 是轻量不可变元组子类。

最小可运行示例

先把示例放进业务场景，再看代码：

场景：订单行项目用 dataclass 建模

# order_line_dataclass.py
# 业务意图：表达订单行并计算行金额。
# 教学点：
# - @dataclass 字段；
# - 自动 repr/eq；
# - 方法仍可手写。

from dataclasses import dataclass


@dataclass
class OrderLine:
    sku: str
    qty: int
    unit_price_cents: int

    def line_total(self) -> int:
        return self.qty * self.unit_price_cents


def main() -> None:
    a = OrderLine("SKU-1", 2, 500)
    b = OrderLine("SKU-1", 2, 500)
    print(a)
    print("eq:", a == b)
    print("total:", a.line_total())


if __name__ == "__main__":
    main()

建议运行：

python order_line_dataclass.py

期望输出：

OrderLine(sku='SKU-1', qty=2, unit_price_cents=500)
eq: True
total: 1000

结合场景再看三个关注点

字段声明即文档。
默认生成的相等比较要求实例类型相同，再比较参与比较的字段值；不等同于任意记录或元组的逐项比较。
frozen=True 阻止普通字段赋值/删除，不会递归冻结字段里的 list 等对象。本例的注解不验证数量、单价类型或非负范围。

核心概念与准确模型

工具	可变	典型用途
`dataclass`	默认可变	领域数据对象
`namedtuple`	槽位不可重新绑定，内部对象仍可变	简单记录、可拆包；相等沿用 tuple 语义
`TypedDict`	运行时是普通可变 dict	静态描述字典结构，不做运行时校验

field(default_factory=list) 避免可变默认坑
slots=True（3.10+）生成 slots 并返回新类；通常省去实例 dict，但若基类已有 dict，仍可能保留。

边界情况与反直觉行为

继承 dataclass 字段顺序规则需查文档。
独立可变默认值通常用 field(default_factory=list)；工厂每次被调用，但若返回同一个全局对象仍会共享。3.11+ 拒绝不可哈希的字段默认值，这是可变性的近似判断。
frozen 实例普通赋值抛 FrozenInstanceError；是否生成 hash 取决于 eq、frozen、unsafe_hash 等配置，实际哈希还要求参与字段可哈希。
asdict 递归转换嵌套数据类/容器，并对其他对象做 deepcopy；不是浅拷贝，也不保证结果可直接 JSON 编码。

常见误区

[!warning] 常见误区：dataclass 替代一切 OOP 错误理解：有数据就 dataclass 到底。
正确模型：富行为/不变量复杂时仍可手写类或加方法约束。

工程实践

API schema 与领域模型分层
序列化边界明确（asdict/外部库）
与类型检查器一起用

本节总结

dataclass 消灭样板；namedtuple 保留元组基因。选更贴数据生命周期的那个。

自测题

为什么 list 字段要用 default_factory？
frozen dataclass 解决什么？

参考答案

避免所有实例共享同一默认 list。
防止普通字段重新赋值或删除，不是深不可变；默认 eq=True, frozen=True 会生成 hash，但含不可哈希字段时实际调用仍会失败。

延伸阅读与资料来源

资料	类型	支撑内容
dataclasses	文档	官方
collections.namedtuple	文档	namedtuple