dataclass 结构化数据

原文：dataclass 结构化数据

一句话

dataclasses模块用于自动为类生成特殊方法，简化结构化数据的定义和使用。

什么时候翻这页

1. 当需要定义Agent工具的输入输出参数，确保类型安全和自动文档生成时
2. 当需要将数据类转换为字典，以便与JSON或其他序列化格式交互时
3. 当需要定义结构化数据类，特别是用于Agent的配置或状态管理时

核心概念

1. dataclass装饰器：自动为类添加__init__()、__repr__()等方法
2. 字段（Field）：使用类型注解定义的类变量，可以有默认值
3. 默认工厂：使用field(default_factory=...)创建可变默认值
4. 冻结实例：设置frozen=True创建不可变对象
5. 仅初始化变量：使用InitVar类型注解，仅在初始化时使用
6. 仅关键字字段：使用KW_ONLY标记，必须通过关键字参数传递

怎么做

1. 基本用法：

from dataclasses import dataclass

@dataclass
class InventoryItem:
    name: str
    unit_price: float
    quantity_on_hand: int = 0

    def total_cost(self) -> float:
        return self.unit_price * self.quantity_on_hand

2. 使用默认工厂处理可变默认值：

from dataclasses import dataclass, field

@dataclass
class C:
    mylist: list[int] = field(default_factory=list)

3. 创建冻结实例：

@dataclass(frozen=True)
class Point:
    x: float
    y: float

4. 使用仅初始化变量：

from dataclasses import dataclass, InitVar

@dataclass
class C:
    i: int
    j: int | None = None
    database: InitVar[DatabaseType | None] = None

    def __post_init__(self, database):
        if self.j is None and database is not None:
            self.j = database.lookup('j')

5. 转换为字典：

from dataclasses import asdict

data_dict = asdict(my_dataclass_instance)

命令 / API 速查

与 Agent 开发的联系

1. 结构化工具参数：使用dataclass定义Agent工具的输入输出参数，确保类型安全和自动文档生成
2. 状态管理：使用冻结数据类存储Agent的不可变状态，防止意外修改
3. 序列化通信：使用asdict()将数据类转换为字典，便于在Agent之间传递结构化数据

初学者易错点

1. 可变默认值陷阱：直接使用可变对象（如列表、字典）作为默认值会导致所有实例共享同一个对象
2. 字段顺序问题：在具有默认值的字段后定义无默认值的字段会导致TypeError
3. 继承字段覆盖：子类中重写字段会覆盖父类的字段定义
4. 冻结实例限制：冻结实例不能修改字段，包括通过__post_init__()设置的值

相关词条

• library-typing 类型提示与注解
• library-json JSON数据处理
• library-copy 对象拷贝操作
• library-functools 函数式工具
• library-types 类型系统支持