使用 attrs 和 cattrs 处理嵌套列表数据结构的最佳实践

本文探讨了如何利用 Python 的 attrs 库优雅地处理包含嵌套列表的复杂数据结构。针对将字典列表转换为 attrs 类实例列表的常见场景，文章阐述了直接使用 converter 参数的局限性，并推荐使用 cattrs 库的 structure 函数。通过实例代码，教程展示了 cattrs 如何自动化地将原始字典数据解构并映射到 attrs 定义的类层级中，从而实现更简洁、健壮的数据转换。

attrs 简介与嵌套数据挑战

attrs 是一个强大的 python 库，用于声明式地定义数据类，它通过装饰器 @define 简化了类的创建，并自动生成 __init__, __repr__, __eq__ 等方法。这使得数据模型定义变得非常简洁和易读。

在实际应用中，我们经常会遇到需要处理嵌套数据结构的情况，例如一个主对象包含一个列表，而列表中的每个元素又是一个复杂的对象。当这些数据最初以字典或 JSON 格式存在时，如何高效且优雅地将其转换为 attrs 定义的类实例，特别是包含列表的场景，是一个常见的挑战。

考虑以下场景：我们有一组角色数据，每个角色包含 first_name 和 last_name。这些角色被组织在一个名为 characters 的列表中，并且整个结构是一个字典。

data = {
    "characters": [
        {"first_name": "Duffy", "last_name": "Duck"},
        {"first_name": "Bugs", "last_name": "Bunny"},
        {"first_name": "Sylvester", "last_name": "Pussycat"},
        {"first_name": "Elmar", "last_name": "Fudd"},
        {"first_name": "Tweety", "last_name": "Bird"},
        {"first_name": "Sam", "last_name": "Yosemite"},
        {"first_name": "Wile E.", "last_name": "Coyote"},
        {"first_name": "Road", "last_name": "Runner"},
    ]
}

我们希望将其映射到以下 attrs 类结构中：

from attrs import define, field
from typing import List

@define(kw_only=True)
class Character:
    first_name: str
    last_name: str

@define
class LooneyToons:
    characters: List[Character]

一个直观但错误的尝试是为 LooneyToons 类中的 characters 字段使用 converter 参数，并将其设置为 Character 类本身：

# 错误的示例，会导致 TypeError
@define
class LooneyToons_Incorrect:
    characters: List[Character] = field(factory=list, converter=Character)

当尝试将 data['characters']（一个字典列表）传递给 LooneyToons_Incorrect 时，会遇到 TypeError: Character.__init__() takes 1 positional argument but 2 were given。这是因为 converter 参数期望接收列表中的每个单独元素，并将其转换为 Character 实例。然而，我们传递给 LooneyToons_Incorrect 构造函数的是整个字典列表，attrs 尝试将整个列表作为单个参数传递给 Character 的 __init__ 方法，这显然是不匹配的。

cattrs：优雅的解决方案

为了解决这种嵌套数据转换的复杂性，cattrs 库应运而生。cattrs 是 attrs 的一个辅助库，专门用于在 Python 对象和各种数据格式（如字典、JSON）之间进行结构化转换（structuring 和 unstructuring）。它能够智能地处理复杂的嵌套结构，包括列表、字典和自定义 attrs 类。

使用 cattrs，我们可以非常简洁地将上述字典数据转换为我们定义的 attrs 类实例。

from typing import List
from attrs import define, field
from cattrs import structure

# 原始数据
data = {
    "characters": [
        {"first_name": "Duffy", "last_name": "Duck"},
        {"first_name": "Bugs", "last_name": "Bunny"},
        {"first_name": "Sylvester", "last_name": "Pussycat"},
        {"first_name": "Elmar", "last_name": "Fudd"},
        {"first_name": "Tweety", "last_name": "Bird"},
        {"first_name": "Sam", "last_name": "Yosemite"},
        {"first_name": "Wile E.", "last_name": "Coyote"},
        {"first_name": "Road", "last_name": "Runner"},
    ]
}

# 定义 Character 类
@define(kw_only=True)
class Character:
    first_name: str
    last_name: str

# 定义 LooneyToons 类，characters 字段无需 converter
@define
class LooneyToons:
    characters: List[Character] = field(factory=list) # factory=list 确保默认值是一个空列表

# 使用 cattrs.structure 进行转换
looney_tunes_instance = structure(data, LooneyToons)

# 验证结果
print(looney_tunes_instance)
print(looney_tunes_instance.characters[0])
print(isinstance(looney_tunes_instance.characters[0], Character))

输出示例：

LooneyToons(characters=[Character(first_name='Duffy', last_name='Duck'), Character(first_name='Bugs', last_name='Bunny'), Character(first_name='Sylvester', last_name='Pussycat'), Character(first_name='Elmar', last_name='Fudd'), Character(first_name='Tweety', last_name='Bird'), Character(first_name='Sam', last_name='Yosemite'), Character(first_name='Wile E.', last_name='Coyote'), Character(first_name='Road', last_name='Runner')])
Character(first_name='Duffy', last_name='Duck')
True

通过 cattrs.structure(data, LooneyToons)，cattrs 会自动检测 LooneyToons 类中的 characters 字段类型是 List[Character]。它会遍历 data['characters'] 中的每一个字典，并智能地将每个字典解构为 Character 类的一个实例。这种方式极大地简化了复杂数据结构的映射过程，避免了手动循环和构造实例。

注意事项与总结

1. 何时使用 converter？ attrs 字段的 converter 参数适用于对单个传入值进行转换。例如，如果 Character 类中的 first_name 字段可能接收数字，你需要将其转换为字符串，那么可以在 first_name 字段上设置 converter=str。但对于将整个列表的字典转换为列表的 attrs 实例，converter 并不适用。
2. cattrs 的强大之处： cattrs 不仅仅处理列表，它还能处理更复杂的嵌套结构，例如字典中的 attrs 类、以及自定义的转换规则。它提供了一个灵活且可扩展的框架来处理数据序列化和反序列化。
3. 类型提示的重要性： 在使用 attrs 和 cattrs 时，清晰准确的类型提示（如 List[Character]）至关重要。cattrs 依赖这些类型信息来正确地进行数据结构化。
4. 安装 cattrs： 如果尚未安装 cattrs，可以使用 pip install cattrs 命令进行安装。

总而言之，当处理涉及 attrs 类和嵌套列表（尤其是从字典数据转换而来）的复杂数据结构时，cattrs 库的 structure 函数是首选的解决方案。它提供了一种声明式、类型安全且高度自动化的方式来完成数据映射，使得代码更加简洁、健壮和易于维护。