Field 对象

Field 对象描述了每个定义的字段。这些对象在内部创建，并由模块级方法 fields() 返回（参见下文）。用户不应直接实例化 Field 对象。其文档属性为

• name：字段的名称。
• type：字段的类型。
• default、default_factory、init、repr、hash、compare 和 metadata 具有与它们在 field() 声明中相同的含义和值。

可能存在其他属性，但它们是私有的，不得检查或依赖。

后初始化处理

生成的 __init__ 代码将调用名为 __post_init__ 的方法（如果它在类上定义）。它将以 self.__post_init__() 的形式调用。如果没有生成 __init__ 方法，则不会自动调用 __post_init__。

除其他用途外，这允许初始化依赖于一个或多个其他字段的字段值。例如

@dataclass
class C:
    a: float
    b: float
    c: float = field(init=False)

    def __post_init__(self):
        self.c = self.a + self.b

有关将参数传递给 __post_init__() 的方法，请参阅下面关于仅初始化变量的部分。另请参阅关于 replace() 如何处理 init=False 字段的警告。

类变量

dataclass 实际检查字段类型的一个地方是确定字段是否是 PEP 526 中定义的类变量。它通过检查字段的类型是否为 typing.ClassVar 来完成此操作。如果字段是 ClassVar，则将其从字段考虑中排除，并被数据类机制忽略。有关更多讨论，请参阅 [8]。此类 ClassVar 伪字段不会由模块级 fields() 函数返回。

仅初始化变量

dataclass 检查类型注解的另一个地方是确定字段是否是仅初始化变量。它通过查看字段的类型是否为 dataclasses.InitVar 来完成此操作。如果字段是 InitVar，则将其视为一个伪字段，称为仅初始化字段。由于它不是真正的字段，因此不会由模块级 fields() 函数返回。仅初始化字段作为参数添加到生成的 __init__ 方法中，并传递给可选的 __post_init__ 方法。数据类不以其他方式使用它们。

例如，假设一个字段将从数据库初始化，如果在创建类时未提供值

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

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

c = C(10, database=my_database)

在这种情况下，fields() 将返回 i 和 j 的 Field 对象，而不是 database 的。

冻结实例

无法创建真正不可变的 Python 对象。但是，通过将 frozen=True 传递给 @dataclass 装饰器，您可以模拟不可变性。在这种情况下，数据类将向类添加 __setattr__ 和 __delattr__ 方法。这些方法在调用时会引发 FrozenInstanceError。

使用 frozen=True 时会有一点性能损失：__init__ 不能使用简单的赋值来初始化字段，而必须使用 object.__setattr__。

继承

当数据类由 @dataclass 装饰器创建时，它会反向遍历所有类的基类 MRO（即从 object 开始），并为找到的每个数据类将该基类的字段添加到字段的有序映射中。在添加所有基类字段后，它将自己的字段添加到有序映射中。所有生成的方法都将使用这个组合的、计算出的有序字段映射。由于字段是按插入顺序排列的，因此派生类会覆盖基类。一个例子

@dataclass
class Base:
    x: Any = 15.0
    y: int = 0

@dataclass
class C(Base):
    z: int = 10
    x: int = 15

字段的最终列表按顺序为 x、y、z。x 的最终类型是 int，如类 C 中指定。

C 的生成的 __init__ 方法将如下所示

def __init__(self, x: int = 15, y: int = 0, z: int = 10):

默认工厂函数

如果字段指定了 default_factory，则当需要该字段的默认值时，将以零参数调用它。例如，要创建列表的新实例，请使用

l: list = field(default_factory=list)

如果一个字段从 __init__ 中排除（使用 init=False），并且该字段还指定了 default_factory，那么默认工厂函数将始终从生成的 __init__ 函数中调用。发生这种情况是因为没有其他方法可以为该字段提供初始值。

可变默认值

Python 将默认成员变量值存储在类属性中。考虑这个不使用数据类的例子

class C:
    x = []
    def add(self, element):
        self.x += element

o1 = C()
o2 = C()
o1.add(1)
o2.add(2)
assert o1.x == [1, 2]
assert o1.x is o2.x

请注意，类 C 的两个实例共享同一个类变量 x，如预期。

使用数据类，如果这段代码有效

@dataclass
class D:
    x: List = []
    def add(self, element):
        self.x += element

它会生成类似于

class D:
    x = []
    def __init__(self, x=x):
        self.x = x
    def add(self, element):
        self.x += element

assert D().x is D().x

这与使用类 C 的原始示例存在相同的问题。也就是说，两个类 D 的实例在创建类实例时未指定 x 的值，将共享同一个 x 的副本。因为数据类只使用普通的 Python 类创建，所以它们也共享这个问题。数据类没有通用的方法来检测这种情况。相反，如果数据类检测到类型为 list、dict 或 set 的默认参数，它将引发 TypeError。这是一个部分解决方案，但它确实可以防止许多常见的错误。有关此选项和其他选项的更多详细信息，请参阅“拒绝的提议”部分中的自动支持可变默认值。

使用默认工厂函数是一种为字段创建可变类型新实例作为默认值的方法

@dataclass
class D:
    x: list = field(default_factory=list)

assert D().x is not D().x

模块级辅助函数

• fields(class_or_instance)：返回一个 Field 对象的元组，这些对象定义了此数据类的字段。接受数据类或数据类的实例。如果未传递数据类或其实例，则引发 ValueError。不返回 ClassVar 或 InitVar 等伪字段。
• asdict(instance, *, dict_factory=dict)：将数据类 instance 转换为字典（通过使用工厂函数 dict_factory）。每个数据类都转换为其字段的字典，作为 name:value 对。数据类、字典、列表和元组都递归处理。例如

  @dataclass
  class Point:
       x: int
       y: int
  
  @dataclass
  class C:
       l: List[Point]
  
  p = Point(10, 20)
  assert asdict(p) == {'x': 10, 'y': 20}
  
  c = C([Point(0, 0), Point(10, 4)])
  assert asdict(c) == {'l': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}
  

  如果 instance 不是数据类实例，则引发 TypeError。

• astuple(*, tuple_factory=tuple)：将数据类 instance 转换为元组（通过使用工厂函数 tuple_factory）。每个数据类都转换为其字段值的元组。数据类、字典、列表和元组都递归处理。

  继续上一个例子

  assert astuple(p) == (10, 20)
  assert astuple(c) == ([(0, 0), (10, 4)],)
  

  如果 instance 不是数据类实例，则引发 TypeError。

• make_dataclass(cls_name, fields, *, bases=(), namespace=None)：创建一个新的数据类，名称为 cls_name，字段定义在 fields 中，基类在 bases 中，并使用 namespace 中给定的命名空间进行初始化。fields 是一个可迭代对象，其元素是 name、(name, type) 或 (name, type, Field)。如果只提供了 name，则 type 使用 typing.Any。此函数并非严格必需，因为任何用于创建带有 __annotations__ 的新类的 Python 机制都可以随后应用 dataclass 函数将该类转换为数据类。此函数作为便利提供。例如

  C = make_dataclass('C',
                     [('x', int),
                       'y',
                      ('z', int, field(default=5))],
                     namespace={'add_one': lambda self: self.x + 1})
  

  等同于

  @dataclass
  class C:
      x: int
      y: 'typing.Any'
      z: int = 5
  
      def add_one(self):
          return self.x + 1
  

• replace(instance, **changes)：创建一个与 instance 相同类型的新对象，用 changes 中的值替换字段。如果 instance 不是数据类，则引发 TypeError。如果 changes 中的值未指定字段，则引发 TypeError。

  新返回的对象是通过调用数据类的 __init__ 方法创建的。这确保了 __post_init__（如果存在）也被调用。

  不带默认值的仅初始化变量（如果存在）必须在调用 replace 时指定，以便它们可以传递给 __init__ 和 __post_init__。

  changes 包含任何被定义为具有 init=False 的字段是错误的。在这种情况下将引发 ValueError。

  请注意 init=False 字段在调用 replace() 期间的工作方式。它们不会从源对象复制，而是在 __post_init__() 中初始化（如果它们被初始化的话）。预计 init=False 字段将很少被谨慎使用。如果使用它们，最好有备用类构造函数，或者自定义 replace()（或类似名称）方法来处理实例复制。

• is_dataclass(class_or_instance)：如果其参数是数据类或数据类实例，则返回 True，否则返回 False。

  如果您需要知道一个类是否是数据类的实例（而不是数据类本身），那么可以添加进一步的检查 not isinstance(obj, type)

  def is_dataclass_instance(obj):
      return is_dataclass(obj) and not isinstance(obj, type)
  

python-ideas 讨论

这次讨论始于 python-ideas [9]，并移至 GitHub 仓库 [10] 进行进一步讨论。作为这次讨论的一部分，我们决定使用 PEP 526 语法来驱动字段的发现。

支持自动设置 __slots__ 吗？

至少在最初版本中，将不支持 __slots__。__slots__ 需要在类创建时添加。数据类装饰器在类创建后被调用，因此为了添加 __slots__，装饰器将不得不创建一个新类，设置 __slots__，并返回它。由于这种行为有些令人惊讶，数据类的初始版本将不支持自动设置 __slots__。有许多变通方法

• 在类定义中手动添加 __slots__。
• 编写一个函数（可以用作装饰器），该函数使用 fields() 检查类，并创建一个设置了 __slots__ 的新类。

有关更多讨论，请参阅 [11]。

为什么不直接使用 namedtuple？

• 任何命名元组都可以与具有相同字段数量的任何其他命名元组意外地进行比较。例如：Point3D(2017, 6, 2) == Date(2017, 6, 2)。使用数据类，这将返回 False。
• 命名元组可能意外地与元组进行比较。例如，Point2D(1, 10) == (1, 10)。使用数据类，这将返回 False。
• 实例总是可迭代的，这使得添加字段变得困难。如果库定义

  Time = namedtuple('Time', ['hour', 'minute'])
  def get_time():
      return Time(12, 0)
  

  那么如果用户使用这段代码作为

  hour, minute = get_time()
  

  那么在不破坏用户代码的情况下，不可能向 Time 添加 second 字段。

• 没有可变实例的选项。
• 无法指定默认值。
• 无法控制哪些字段用于 __init__、__repr__ 等。
• 无法支持通过继承组合字段。

为什么不直接使用 typing.NamedTuple？

对于具有静态定义字段的类，它确实支持与数据类相似的语法，使用类型注解。这会生成一个命名元组，因此它共享 namedtuple 的优点和一些缺点。数据类，与 typing.NamedTuple 不同，支持通过继承组合字段。

为什么不直接使用 attrs？

• Attrs 的发展速度比将其纳入标准库所能适应的速度更快。
• Attrs 支持此处未提议的其他功能：验证器、转换器、元数据等。数据类为了实现简单性而选择不实现这些功能。

有关更多讨论，请参阅 [12]。

后初始化参数

在添加 InitVar 之前的本 PEP 早期版本中，后初始化函数 __post_init__ 从未接受任何参数。

参数化初始化（不限于数据类）的常规方法是提供一个备用类方法构造函数。例如

@dataclass
class C:
    x: int

    @classmethod
    def from_file(cls, filename):
        with open(filename) as fl:
            file_value = int(fl.read())
        return C(file_value)

c = C.from_file('file.txt')

因为 __post_init__ 函数是生成的 __init__ 中最后被调用的，所以拥有一个类方法构造函数（它也可以在构造对象后立即执行代码）在功能上等同于能够将参数传递给 __post_init__ 函数。

使用 InitVars，__post_init__ 函数现在可以接受参数。它们首先传递给 __init__，后者将它们传递给 __post_init__，用户代码可以在那里根据需要使用它们。

备用类方法构造函数和 InitVar 伪字段之间的唯一真正区别在于对象创建期间所需的非字段参数。使用 InitVars，使用 __init__ 和模块级 replace() 函数时，必须始终指定 InitVars。考虑创建实例需要 context 对象但未将其存储为字段的情况。使用备用类方法构造函数，context 参数始终是可选的，因为您仍然可以通过 __init__ 创建对象（除非您抑制其创建）。哪种方法更合适将取决于应用程序，但两种方法都受支持。

使用 InitVar 字段的另一个原因是类作者可以控制 __init__ 参数的顺序。这对于具有默认值的常规字段和 InitVar 字段尤其重要，因为所有具有默认值的字段都必须位于所有没有默认值的字段之后。以前的设计是所有仅初始化字段都位于常规字段之后。这意味着如果任何字段具有默认值，则所有仅初始化字段也必须具有默认值。

asdict 和 astuple 函数名称

模块级辅助函数 asdict() 和 astuple() 的名称可以说不符合 PEP 8 规范，应该分别是 as_dict() 和 as_tuple()。然而，经过讨论 [13]，决定保持与 namedtuple._asdict() 和 attr.asdict() 的一致性。

在 replace() 中新对象创建后复制 init=False 字段

被定义为 init=False 的字段，根据定义不会传递给 __init__，而是通过默认值初始化，或在 __init__ 中调用默认工厂函数，或通过 __post_init__ 中的代码初始化。

本 PEP 的先前版本规定，在 __init__ 返回后，init=False 字段将从源对象复制到新创建的对象，但这被认为与使用 __init__ 和 __post_init__ 初始化新对象不一致。例如，考虑以下情况

@dataclass
class Square:
    length: float
    area: float = field(init=False, default=0.0)

    def __post_init__(self):
        self.area = self.length * self.length

s1 = Square(1.0)
s2 = replace(s1, length=2.0)

如果 init=False 字段在 __post_init__ 运行后从源对象复制到目标对象，那么 s2 最终将是 Square(length=2.0, area=1.0)，而不是正确的 Square(length=2.0, area=4.0)。

自动支持可变默认值

一个提议是自动复制默认值，以便如果字面量列表 [] 是默认值，每个实例将获得一个新的列表。这个决定有一些不希望的副作用，所以最终决定是不允许 3 种已知的内置可变类型：list、dict 和 set。有关此选项和其他选项的完整讨论，请参阅 [14]。

自定义 __init__ 方法

有时生成的 __init__ 方法不足。例如，假设您想拥有一个对象来存储 *args 和 **kwargs

@dataclass(init=False)
class ArgHolder:
    args: List[Any]
    kwargs: Mapping[Any, Any]

    def __init__(self, *args, **kwargs):
        self.args = args
        self.kwargs = kwargs

a = ArgHolder(1, 2, three=3)

一个复杂的例子

此代码存在于一个闭源项目中

class Application:
    def __init__(self, name, requirements, constraints=None, path='', executable_links=None, executables_dir=()):
        self.name = name
        self.requirements = requirements
        self.constraints = {} if constraints is None else constraints
        self.path = path
        self.executable_links = [] if executable_links is None else executable_links
        self.executables_dir = executables_dir
        self.additional_items = []

    def __repr__(self):
        return f'Application({self.name!r},{self.requirements!r},{self.constraints!r},{self.path!r},{self.executable_links!r},{self.executables_dir!r},{self.additional_items!r})'

这可以替换为

@dataclass
class Application:
    name: str
    requirements: List[Requirement]
    constraints: Dict[str, str] = field(default_factory=dict)
    path: str = ''
    executable_links: List[str] = field(default_factory=list)
    executable_dir: Tuple[str] = ()
    additional_items: List[str] = field(init=False, default_factory=list)

数据类版本更具声明性，代码更少，支持 typing，并包含其他生成的函数。