@@ -49,26 +49,26 @@ Module contents
49
49
.. decorator :: dataclass(*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)
50
50
51
51
This function is a :term: `decorator ` that is used to add generated
52
- :term: `special method ` \s to classes, as described below.
52
+ :term: `special methods <special method> ` to classes, as described below.
53
53
54
- The :func: `dataclass ` decorator examines the class to find
54
+ The :func: `! dataclass ` decorator examines the class to find
55
55
``field ``\s . A ``field `` is defined as a class variable that has a
56
56
:term: `type annotation <variable annotation> `. With two
57
- exceptions described below, nothing in :func: `dataclass `
57
+ exceptions described below, nothing in :func: `! dataclass `
58
58
examines the type specified in the variable annotation.
59
59
60
60
The order of the fields in all of the generated methods is the
61
61
order in which they appear in the class definition.
62
62
63
- The :func: `dataclass ` decorator will add various "dunder" methods to
63
+ The :func: `! dataclass ` decorator will add various "dunder" methods to
64
64
the class, described below. If any of the added methods already
65
65
exist in the class, the behavior depends on the parameter, as documented
66
66
below. The decorator returns the same class that it is called on; no new
67
67
class is created.
68
68
69
- If :func: `dataclass ` is used just as a simple decorator with no parameters,
69
+ If :func: `! dataclass ` is used just as a simple decorator with no parameters,
70
70
it acts as if it has the default values documented in this
71
- signature. That is, these three uses of :func: `dataclass ` are
71
+ signature. That is, these three uses of :func: `! dataclass ` are
72
72
equivalent::
73
73
74
74
@dataclass
@@ -84,7 +84,7 @@ Module contents
84
84
class C:
85
85
...
86
86
87
- The parameters to :func: `dataclass ` are:
87
+ The parameters to :func: `! dataclass ` are:
88
88
89
89
- ``init ``: If true (the default), a :meth: `~object.__init__ ` method will be
90
90
generated.
@@ -129,17 +129,17 @@ Module contents
129
129
:meth: `~object.__hash__ ` implies that instances of the class are immutable.
130
130
Mutability is a complicated property that depends on the programmer's
131
131
intent, the existence and behavior of :meth: `~object.__eq__ `, and the values of
132
- the ``eq `` and ``frozen `` flags in the :func: `dataclass ` decorator.
132
+ the ``eq `` and ``frozen `` flags in the :func: `! dataclass ` decorator.
133
133
134
- By default, :func: `dataclass ` will not implicitly add a :meth: `~object.__hash__ `
134
+ By default, :func: `! dataclass ` will not implicitly add a :meth: `~object.__hash__ `
135
135
method unless it is safe to do so. Neither will it add or change an
136
136
existing explicitly defined :meth: `~object.__hash__ ` method. Setting the class
137
137
attribute ``__hash__ = None `` has a specific meaning to Python, as
138
138
described in the :meth: `~object.__hash__ ` documentation.
139
139
140
140
If :meth: `~object.__hash__ ` is not explicitly defined, or if it is set to ``None ``,
141
- then :func: `dataclass ` *may * add an implicit :meth: `~object.__hash__ ` method.
142
- Although not recommended, you can force :func: `dataclass ` to create a
141
+ then :func: `! dataclass ` *may * add an implicit :meth: `~object.__hash__ ` method.
142
+ Although not recommended, you can force :func: `! dataclass ` to create a
143
143
:meth: `~object.__hash__ ` method with ``unsafe_hash=True ``. This might be the case
144
144
if your class is logically immutable but can still be mutated.
145
145
This is a specialized use case and should be considered carefully.
@@ -149,7 +149,7 @@ Module contents
149
149
method in your dataclass and set ``unsafe_hash=True ``; this will result
150
150
in a :exc: `TypeError `.
151
151
152
- If ``eq `` and ``frozen `` are both true, by default :func: `dataclass ` will
152
+ If ``eq `` and ``frozen `` are both true, by default :func: `! dataclass ` will
153
153
generate a :meth: `~object.__hash__ ` method for you. If ``eq `` is true and
154
154
``frozen `` is false, :meth: `~object.__hash__ ` will be set to ``None ``, marking it
155
155
unhashable (which it is, since it is mutable). If ``eq `` is false,
@@ -229,7 +229,7 @@ Module contents
229
229
required. There are, however, some dataclass features that
230
230
require additional per-field information. To satisfy this need for
231
231
additional information, you can replace the default field value
232
- with a call to the provided :func: `field ` function. For example::
232
+ with a call to the provided :func: `! field ` function. For example::
233
233
234
234
@dataclass
235
235
class C:
@@ -243,10 +243,10 @@ Module contents
243
243
used because ``None `` is a valid value for some parameters with
244
244
a distinct meaning. No code should directly use the :const: `MISSING ` value.
245
245
246
- The parameters to :func: `field ` are:
246
+ The parameters to :func: `! field ` are:
247
247
248
248
- ``default ``: If provided, this will be the default value for this
249
- field. This is needed because the :meth: ` field ` call itself
249
+ field. This is needed because the :func: ` ! field ` call itself
250
250
replaces the normal position of the default value.
251
251
252
252
- ``default_factory ``: If provided, it must be a zero-argument
@@ -293,7 +293,7 @@ Module contents
293
293
.. versionadded :: 3.10
294
294
295
295
If the default value of a field is specified by a call to
296
- :func: `field() `, then the class attribute for this field will be
296
+ :func: `! field `, then the class attribute for this field will be
297
297
replaced by the specified ``default `` value. If no ``default `` is
298
298
provided, then the class attribute will be deleted. The intent is
299
299
that after the :func: `dataclass ` decorator runs, the class
@@ -343,7 +343,7 @@ Module contents
343
343
lists, and tuples are recursed into. Other objects are copied with
344
344
:func: `copy.deepcopy `.
345
345
346
- Example of using :func: `asdict ` on nested dataclasses::
346
+ Example of using :func: `! asdict ` on nested dataclasses::
347
347
348
348
@dataclass
349
349
class Point:
@@ -364,7 +364,7 @@ Module contents
364
364
365
365
dict((field.name, getattr(obj, field.name)) for field in fields(obj))
366
366
367
- :func: `asdict ` raises :exc: `TypeError ` if ``obj `` is not a dataclass
367
+ :func: `! asdict ` raises :exc: `TypeError ` if ``obj `` is not a dataclass
368
368
instance.
369
369
370
370
.. function :: astuple(obj, *, tuple_factory=tuple)
@@ -384,7 +384,7 @@ Module contents
384
384
385
385
tuple(getattr(obj, field.name) for field in dataclasses.fields(obj))
386
386
387
- :func: `astuple ` raises :exc: `TypeError ` if ``obj `` is not a dataclass
387
+ :func: `! astuple ` raises :exc: `TypeError ` if ``obj `` is not a dataclass
388
388
instance.
389
389
390
390
.. function :: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False, module=None)
@@ -438,15 +438,15 @@ Module contents
438
438
:meth: `__post_init__ `, if present, is also called.
439
439
440
440
Init-only variables without default values, if any exist, must be
441
- specified on the call to :func: `replace ` so that they can be passed to
441
+ specified on the call to :func: `! replace ` so that they can be passed to
442
442
:meth: `~object.__init__ ` and :meth: `__post_init__ `.
443
443
444
444
It is an error for ``changes `` to contain any fields that are
445
445
defined as having ``init=False ``. A :exc: `ValueError ` will be raised
446
446
in this case.
447
447
448
448
Be forewarned about how ``init=False `` fields work during a call to
449
- :func: `replace `. They are not copied from the source object, but
449
+ :func: `! replace `. They are not copied from the source object, but
450
450
rather are initialized in :meth: `__post_init__ `, if they're
451
451
initialized at all. It is expected that ``init=False `` fields will
452
452
be rarely and judiciously used. If they are used, it might be wise
@@ -475,11 +475,11 @@ Module contents
475
475
.. data :: KW_ONLY
476
476
477
477
A sentinel value used as a type annotation. Any fields after a
478
- pseudo-field with the type of :const: `KW_ONLY ` are marked as
478
+ pseudo-field with the type of :const: `! KW_ONLY ` are marked as
479
479
keyword-only fields. Note that a pseudo-field of type
480
- :const: `KW_ONLY ` is otherwise completely ignored. This includes the
480
+ :const: `! KW_ONLY ` is otherwise completely ignored. This includes the
481
481
name of such a field. By convention, a name of ``_ `` is used for a
482
- :const: `KW_ONLY ` field. Keyword-only fields signify
482
+ :const: `! KW_ONLY ` field. Keyword-only fields signify
483
483
:meth: `~object.__init__ ` parameters that must be specified as keywords when
484
484
the class is instantiated.
485
485
@@ -495,7 +495,7 @@ Module contents
495
495
p = Point(0, y=1.5, z=2.0)
496
496
497
497
In a single dataclass, it is an error to specify more than one
498
- field whose type is :const: `KW_ONLY `.
498
+ field whose type is :const: `! KW_ONLY `.
499
499
500
500
.. versionadded :: 3.10
501
501
@@ -515,9 +515,9 @@ Post-init processing
515
515
When defined on the class, it will be called by the generated
516
516
:meth: `~object.__init__ `, normally as ``self.__post_init__() ``.
517
517
However, if any ``InitVar `` fields are defined, they will also be
518
- passed to :meth: `__post_init__ ` in the order they were defined in the
518
+ passed to :meth: `! __post_init__ ` in the order they were defined in the
519
519
class. If no :meth: `~object.__init__ ` method is generated, then
520
- :meth: `__post_init__ ` will not automatically be called.
520
+ :meth: `! __post_init__ ` will not automatically be called.
521
521
522
522
Among other uses, this allows for initializing field values that
523
523
depend on one or more other fields. For example::
0 commit comments