Field 对象

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

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

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

post-init 处理

生成的 __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，则 typing.Any 将用作 type。此函数不是严格要求的，因为任何用于创建具有 __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]。

post-init 参数

在添加 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__ 函数传递参数。

使用 InitVar，__post_init__ 函数现在可以接受参数。它们首先被传递给 __init__，然后由 __init__ 传递给 __post_init__，用户代码可以在其中根据需要使用它们。

备用类方法构造函数和 InitVar 伪字段之间唯一的真正区别在于在对象创建期间是否需要非字段参数。对于 InitVar，使用 __init__ 和模块级 replace() 函数，InitVar 必须始终指定。考虑这样一种情况，在其中需要一个 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)

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

自动支持可变默认值

一项提议是自动复制默认值，以便如果一个文字列表 [] 是一个默认值，那么每个实例都会获得一个新列表。这个决定的副作用是不希望的，因此最终决定是不允许 3 种已知的内置可变类型：列表、字典和集合。有关此主题和其他选项的完整讨论，请参见 [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，并且包含其他生成的函数。