cattrs：Python 数据结构化与校验工具

python-attrs/cattrs 收获了 1,036 个 Star：

cattrs 是一个 Python 库，专注于非结构化数据与结构化对象之间的双向转换，并在转换过程中完成类型校验。

cattrs 与 attrs 和 Python 标准库的 dataclasses 配合使用效果最佳。它可以将原始字典转换成带有类型约束的 Python 类实例，也可以将实例反向序列化为纯字典。整个过程中，类型注解被用作校验依据，模型本身不需要混入任何序列化逻辑。

基本用法很直接：

from attrs import define
from cattrs import structure, unstructure

@define
class C:
    a: int
    b: list[str]

instance = structure({'a': 1, 'b': ['x', 'y']}, C)
instance
# 输出: C(a=1, b=['x', 'y'])

unstructure(instance)
# 输出: {'a': 1, 'b': ['x', 'y']}

structure 函数接收原始数据和目标类型，输出对应类型的实例。unstructure 函数执行相反操作，将实例还原为原始数据结构。两者都支持嵌套类型自动处理，无需额外配置。

cattrs 的递归 structuring 覆盖了日常开发中的绝大多数类型场景：

• Optional[T] 和 Python 3.10 引入的 T | None
• list[T]、tuple（含定长 tuple[X, Y, Z] 和变长 tuple[T, …] 两种形式）
• set[T]、frozenset[T]
• dict[K, V] 及 Mapping、MutableMapping 的各变种
• TypedDict（含泛型形式）
• NewType 和 Python 3.12 的 PEP 695 类型别名
• attrs 类和 dataclasses
• 嵌套组合以及 Union 类型（要求各分支类具备可区分的字段）

如果内置类型不够覆盖需求，可以通过 register_structure_hook 和 register_unstructure_hook 注册自定义转换逻辑。

在生态集成方面，cattrs 内置了多种序列化库的预配置转换器，开箱即用。支持的库覆盖标准库 json、orjson、ujson、msgpack、cbor2、bson、PyYAML、tomlkit 和 msgspec。

项目的架构基于三条核心设计决策：

第一条是规则与模型分离。转换逻辑不硬编码在数据类内部，这意味着同一模型可以绑定多套不同的序列化规则，也能为不可修改的第三方类定义转换行为。需要时也可以切换到类方法策略。

第二条是复用原生机制。cattrs 倾向于复用 Python 标准语法和标准异常类型，而非发明自定义概念。例如聚合异常功能，是在 Python 标准库引入 ExceptionGroup 之后才跟进支持的。这个设计带来一个附带效果：排查 cattrs 问题的过程往往也是加深对 Python 类型系统理解的过程。因为你在解决的并不是某个框架特有的怪异行为，而是在学习 Python 本身的类型机制和异常处理模型。

第三条是拒绝猜测。当存在多种合理处理方式时，cattrs 不会替用户做隐式决定，而是暴露配置点由用户显式指定。这减少了意外行为，也让代码意图更清晰。

这三条原则让 cattrs 在功能完整的同时保持了轻量的体积和平缓的学习曲线。

外行为，也让代码意图更清晰。

这三条原则让 cattrs 在功能完整的同时保持了轻量的体积和平缓的学习曲线。