dataclasses --- 数据类 — Python 3.10.13 文档
dataclass() 的参数有:
-
init
: 如果为真值(默认),将生成一个__init__()
方法。如果类已定义
__init__()
,则忽略此参数。 -
repr
:如果为真值(默认),将生成一个__repr__()
方法。 生成的 repr 字符串将具有类名以及每个字段的名称和 repr ,按照它们在类中定义的顺序。不包括标记为从 repr 中排除的字段。 例如:InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10)
。如果类已定义
__repr__()
,则忽略此参数。 -
eq
:如果为true(默认值),将生成__eq__()
方法。此方法将类作为其字段的元组按顺序比较。比较中的两个实例必须是相同的类型。如果类已定义
__eq__()
,则忽略此参数。 -
order
:如果为真值(默认为False
),则__lt__()
、__le__()
、__gt__()
和__ge__()
方法将生成。 这将类作为其字段的元组按顺序比较。比较中的两个实例必须是相同的类型。如果order
为真值并且eq
为假值 ,则引发 ValueError 。如果类已经定义了
__lt__()
、__le__()
、__gt__()
或者__ge__()
中的任意一个,将引发 TypeError 。 -
unsafe_hash
:如果为False
(默认值),则根据eq
和frozen
的设置方式生成__hash__()
方法。__hash__()
由内置的 hash() 使用,当对象被添加到散列集合(如字典和集合)时。有一个__hash__()
意味着类的实例是不可变的。可变性是一个复杂的属性,取决于程序员的意图,__eq__()
的存在性和行为,以及 dataclass() 装饰器中eq
和frozen
标志的值。默认情况下, dataclass() 不会隐式添加
__hash__()
方法,除非这样做是安全的。 它也不会添加或更改现有的明确定义的__hash__()
方法。 设置类属性__hash__ = None
对 Python 具有特定含义,如__hash__()
文档中所述。如果
__hash__()
没有显式定义,或者它被设为None
,则 dataclass() 可能 会添加一个隐式__hash__()
方法。 虽然并不推荐,但你可以用unsafe_hash=True
来强制 dataclass() 创建一个__hash__()
方法。 如果你的类在逻辑上不可变但却仍然可被修改那么可能就是这种情况。 这是一个特殊用例并且应当被仔细地考虑。以下是隐式创建
__hash__()
方法的规则。请注意,你不能在数据类中都使用显式的__hash__()
方法并设置unsafe_hash=True
;这将导致 TypeError 。如果
eq
和frozen
都是 true,默认情况下 dataclass() 将为你生成一个__hash__()
方法。如果eq
为 true 且frozen
为 false ,则__hash__()
将被设置为None
,标记它不可用(因为它是可变的)。如果eq
为 false ,则__hash__()
将保持不变,这意味着将使用超类的__hash__()
方法(如果超类是 object ,这意味着它将回到基于id的hash)。 -
frozen
: 如为真值 (默认值为False
),则对字段赋值将会产生异常。 这模拟了只读的冻结实例。 如果在类中定义了__setattr__()
或__delattr__()
则将会引发 TypeError。 参见下文的讨论。 -
match_args
: 如果为真值 (默认值为True
),则将根据传给生成的__init__()
方法的形参列表来创建__match_args__
元组 (即使没有生成__init__()
也会创建,见上文)。 如果为假值,或者如果__match_args__
已在类中定义,则将不生成__match_args__
。
3.10 新版功能.
-
kw_only
: 如果为真值 (默认值为False
),则所有字段都将被标记为仅限关键字。 如果一个字段被标记为仅限关键字,则其唯一的影响是根据仅限关键字的字段生成的__init__()
形参必须使用调用__init__()
时传入的关键字来指定。 对于 dataclass 的任何其它方面都没有影响。 请参阅 parameter 术语表条目了解详情。 另请参阅 KW_ONLY 一节。
field() 的形参有:
-
default
:如果提供,这将是该字段的默认值。设计这个形参是因为 field() 调用将会占据原来用来提供默认值的位置。 -
default_factory
:如果提供,它必须是一个需要零个参数的可调用对象,当该字段需要一个默认值时,它将被调用。这能解决当默认值是可变对象时会带来的问题,如下所述。同时指定default
和default_factory
将产生错误。 -
init
:如果为true(默认值),则该字段作为参数包含在生成的__init__()
方法中。 -
repr
:如果为true(默认值),则该字段包含在生成的__repr__()
方法返回的字符串中。 -
hash
:这可以是布尔值或None
。如果为true,则此字段包含在生成的__hash__()
方法中。如果为None
(默认值),请使用compare
的值,这通常是预期的行为。如果字段用于比较,则应在 hash 中考虑该字段。不鼓励将此值设置为None
以外的任何值。设置
hash=False
但compare=True
的一个合理情况是,一个计算哈希值的代价很高的字段是检验等价性需要的,且还有其他字段可以用于计算类型的哈希值。可以从哈希值中排除该字段,但仍令它用于比较。 -
compare
:如果为true(默认值),则该字段包含在生成的相等性和比较方法中(__eq__()
,__gt__()
等等)。 -
metadata
:可以是映射或 None。None 被视为一个空的字典。这个值将被包装在 MappingProxyType() 中,使其只读,并暴露在 Field 对象上。数据类不使用它——它是作为第三方扩展机制提供的。多个第三方可以各自拥有自己的键,以用作元数据中的命名空间。 -
kw_only
: 如果为真值,则此字段将被标记为仅限关键字。 这将在当计算出所生成的__init__()
方法的形参时被使用。