Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 56d50dd

Browse filesBrowse files
ambvolgarithms
ambv
and
olgarithms
authored
[3.11] gh-103810: Fix broken references in dataclasses (GH-103811) (#103813)
(cherry picked from commit 0f23eda) Co-authored-by: Olga Matoula <olgamatoula@gmail.com>
1 parent 9f43643 commit 56d50dd
Copy full SHA for 56d50dd

File tree

Expand file treeCollapse file tree

1 file changed

+74
-72
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+74
-72
lines changed

‎Doc/library/dataclasses.rst

Copy file name to clipboardExpand all lines: Doc/library/dataclasses.rst
+74-72Lines changed: 74 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@
1212
--------------
1313

1414
This module provides a decorator and functions for automatically
15-
adding generated :term:`special method`\s such as :meth:`__init__` and
16-
:meth:`__repr__` to user-defined classes. It was originally described
15+
adding generated :term:`special method`\s such as :meth:`~object.__init__` and
16+
:meth:`~object.__repr__` to user-defined classes. It was originally described
1717
in :pep:`557`.
1818

1919
The member variables to use in these generated methods are defined
@@ -31,7 +31,7 @@ using :pep:`526` type annotations. For example, this code::
3131
def total_cost(self) -> float:
3232
return self.unit_price * self.quantity_on_hand
3333

34-
will add, among other things, a :meth:`__init__` that looks like::
34+
will add, among other things, a :meth:`~object.__init__` that looks like::
3535

3636
def __init__(self, name: str, unit_price: float, quantity_on_hand: int = 0):
3737
self.name = name
@@ -86,105 +86,105 @@ Module contents
8686

8787
The parameters to :func:`dataclass` are:
8888

89-
- ``init``: If true (the default), a :meth:`__init__` method will be
89+
- ``init``: If true (the default), a :meth:`~object.__init__` method will be
9090
generated.
9191

92-
If the class already defines :meth:`__init__`, this parameter is
92+
If the class already defines :meth:`~object.__init__`, this parameter is
9393
ignored.
9494

95-
- ``repr``: If true (the default), a :meth:`__repr__` method will be
95+
- ``repr``: If true (the default), a :meth:`~object.__repr__` method will be
9696
generated. The generated repr string will have the class name and
9797
the name and repr of each field, in the order they are defined in
9898
the class. Fields that are marked as being excluded from the repr
9999
are not included. For example:
100100
``InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10)``.
101101

102-
If the class already defines :meth:`__repr__`, this parameter is
102+
If the class already defines :meth:`~object.__repr__`, this parameter is
103103
ignored.
104104

105-
- ``eq``: If true (the default), an :meth:`__eq__` method will be
105+
- ``eq``: If true (the default), an :meth:`~object.__eq__` method will be
106106
generated. This method compares the class as if it were a tuple
107107
of its fields, in order. Both instances in the comparison must
108108
be of the identical type.
109109

110-
If the class already defines :meth:`__eq__`, this parameter is
110+
If the class already defines :meth:`~object.__eq__`, this parameter is
111111
ignored.
112112

113-
- ``order``: If true (the default is ``False``), :meth:`__lt__`,
114-
:meth:`__le__`, :meth:`__gt__`, and :meth:`__ge__` methods will be
113+
- ``order``: If true (the default is ``False``), :meth:`~object.__lt__`,
114+
:meth:`~object.__le__`, :meth:`~object.__gt__`, and :meth:`~object.__ge__` methods will be
115115
generated. These compare the class as if it were a tuple of its
116116
fields, in order. Both instances in the comparison must be of the
117117
identical type. If ``order`` is true and ``eq`` is false, a
118118
:exc:`ValueError` is raised.
119119

120-
If the class already defines any of :meth:`__lt__`,
121-
:meth:`__le__`, :meth:`__gt__`, or :meth:`__ge__`, then
120+
If the class already defines any of :meth:`~object.__lt__`,
121+
:meth:`~object.__le__`, :meth:`~object.__gt__`, or :meth:`~object.__ge__`, then
122122
:exc:`TypeError` is raised.
123123

124-
- ``unsafe_hash``: If ``False`` (the default), a :meth:`__hash__` method
124+
- ``unsafe_hash``: If ``False`` (the default), a :meth:`~object.__hash__` method
125125
is generated according to how ``eq`` and ``frozen`` are set.
126126

127-
:meth:`__hash__` is used by built-in :meth:`hash()`, and when objects are
127+
:meth:`~object.__hash__` is used by built-in :meth:`hash()`, and when objects are
128128
added to hashed collections such as dictionaries and sets. Having a
129-
:meth:`__hash__` implies that instances of the class are immutable.
129+
:meth:`~object.__hash__` implies that instances of the class are immutable.
130130
Mutability is a complicated property that depends on the programmer's
131-
intent, the existence and behavior of :meth:`__eq__`, and the values of
131+
intent, the existence and behavior of :meth:`~object.__eq__`, and the values of
132132
the ``eq`` and ``frozen`` flags in the :func:`dataclass` decorator.
133133

134-
By default, :func:`dataclass` will not implicitly add a :meth:`__hash__`
134+
By default, :func:`dataclass` will not implicitly add a :meth:`~object.__hash__`
135135
method unless it is safe to do so. Neither will it add or change an
136-
existing explicitly defined :meth:`__hash__` method. Setting the class
136+
existing explicitly defined :meth:`~object.__hash__` method. Setting the class
137137
attribute ``__hash__ = None`` has a specific meaning to Python, as
138-
described in the :meth:`__hash__` documentation.
138+
described in the :meth:`~object.__hash__` documentation.
139139

140-
If :meth:`__hash__` is not explicitly defined, or if it is set to ``None``,
141-
then :func:`dataclass` *may* add an implicit :meth:`__hash__` method.
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.
142142
Although not recommended, you can force :func:`dataclass` to create a
143-
:meth:`__hash__` method with ``unsafe_hash=True``. This might be the case
143+
:meth:`~object.__hash__` method with ``unsafe_hash=True``. This might be the case
144144
if your class is logically immutable but can nonetheless be mutated.
145145
This is a specialized use case and should be considered carefully.
146146

147-
Here are the rules governing implicit creation of a :meth:`__hash__`
148-
method. Note that you cannot both have an explicit :meth:`__hash__`
147+
Here are the rules governing implicit creation of a :meth:`~object.__hash__`
148+
method. Note that you cannot both have an explicit :meth:`~object.__hash__`
149149
method in your dataclass and set ``unsafe_hash=True``; this will result
150150
in a :exc:`TypeError`.
151151

152152
If ``eq`` and ``frozen`` are both true, by default :func:`dataclass` will
153-
generate a :meth:`__hash__` method for you. If ``eq`` is true and
154-
``frozen`` is false, :meth:`__hash__` will be set to ``None``, marking it
153+
generate a :meth:`~object.__hash__` method for you. If ``eq`` is true and
154+
``frozen`` is false, :meth:`~object.__hash__` will be set to ``None``, marking it
155155
unhashable (which it is, since it is mutable). If ``eq`` is false,
156-
:meth:`__hash__` will be left untouched meaning the :meth:`__hash__`
156+
:meth:`~object.__hash__` will be left untouched meaning the :meth:`~object.__hash__`
157157
method of the superclass will be used (if the superclass is
158158
:class:`object`, this means it will fall back to id-based hashing).
159159

160160
- ``frozen``: If true (the default is ``False``), assigning to fields will
161161
generate an exception. This emulates read-only frozen instances. If
162-
:meth:`__setattr__` or :meth:`__delattr__` is defined in the class, then
162+
:meth:`~object.__setattr__` or :meth:`~object.__delattr__` is defined in the class, then
163163
:exc:`TypeError` is raised. See the discussion below.
164164

165165
- ``match_args``: If true (the default is ``True``), the
166166
``__match_args__`` tuple will be created from the list of
167-
parameters to the generated :meth:`__init__` method (even if
168-
:meth:`__init__` is not generated, see above). If false, or if
167+
parameters to the generated :meth:`~object.__init__` method (even if
168+
:meth:`~object.__init__` is not generated, see above). If false, or if
169169
``__match_args__`` is already defined in the class, then
170170
``__match_args__`` will not be generated.
171171

172172
.. versionadded:: 3.10
173173

174174
- ``kw_only``: If true (the default value is ``False``), then all
175175
fields will be marked as keyword-only. If a field is marked as
176-
keyword-only, then the only effect is that the :meth:`__init__`
176+
keyword-only, then the only effect is that the :meth:`~object.__init__`
177177
parameter generated from a keyword-only field must be specified
178-
with a keyword when :meth:`__init__` is called. There is no
178+
with a keyword when :meth:`~object.__init__` is called. There is no
179179
effect on any other aspect of dataclasses. See the
180180
:term:`parameter` glossary entry for details. Also see the
181181
:const:`KW_ONLY` section.
182182

183183
.. versionadded:: 3.10
184184

185-
- ``slots``: If true (the default is ``False``), :attr:`__slots__` attribute
185+
- ``slots``: If true (the default is ``False``), :attr:`~object.__slots__` attribute
186186
will be generated and new class will be returned instead of the original one.
187-
If :attr:`__slots__` is already defined in the class, then :exc:`TypeError`
187+
If :attr:`~object.__slots__` is already defined in the class, then :exc:`TypeError`
188188
is raised.
189189

190190
.. versionadded:: 3.10
@@ -215,7 +215,7 @@ Module contents
215215
b: int = 0 # assign a default value for 'b'
216216

217217
In this example, both ``a`` and ``b`` will be included in the added
218-
:meth:`__init__` method, which will be defined as::
218+
:meth:`~object.__init__` method, which will be defined as::
219219

220220
def __init__(self, a: int, b: int = 0):
221221

@@ -256,13 +256,13 @@ Module contents
256256
error to specify both ``default`` and ``default_factory``.
257257

258258
- ``init``: If true (the default), this field is included as a
259-
parameter to the generated :meth:`__init__` method.
259+
parameter to the generated :meth:`~object.__init__` method.
260260

261261
- ``repr``: If true (the default), this field is included in the
262-
string returned by the generated :meth:`__repr__` method.
262+
string returned by the generated :meth:`~object.__repr__` method.
263263

264264
- ``hash``: This can be a bool or ``None``. If true, this field is
265-
included in the generated :meth:`__hash__` method. If ``None`` (the
265+
included in the generated :meth:`~object.__hash__` method. If ``None`` (the
266266
default), use the value of ``compare``: this would normally be
267267
the expected behavior. A field should be considered in the hash
268268
if it's used for comparisons. Setting this value to anything
@@ -275,8 +275,8 @@ Module contents
275275
is excluded from the hash, it will still be used for comparisons.
276276

277277
- ``compare``: If true (the default), this field is included in the
278-
generated equality and comparison methods (:meth:`__eq__`,
279-
:meth:`__gt__`, et al.).
278+
generated equality and comparison methods (:meth:`~object.__eq__`,
279+
:meth:`~object.__gt__`, et al.).
280280

281281
- ``metadata``: This can be a mapping or None. None is treated as
282282
an empty dict. This value is wrapped in
@@ -287,7 +287,7 @@ Module contents
287287
namespace in the metadata.
288288

289289
- ``kw_only``: If true, this field will be marked as keyword-only.
290-
This is used when the generated :meth:`__init__` method's
290+
This is used when the generated :meth:`~object.__init__` method's
291291
parameters are computed.
292292

293293
.. versionadded:: 3.10
@@ -431,21 +431,21 @@ Module contents
431431
Class, raises :exc:`TypeError`. If values in ``changes`` do not
432432
specify fields, raises :exc:`TypeError`.
433433

434-
The newly returned object is created by calling the :meth:`__init__`
434+
The newly returned object is created by calling the :meth:`~object.__init__`
435435
method of the dataclass. This ensures that
436-
:meth:`__post_init__`, if present, is also called.
436+
:ref:`__post_init__ <post-init-processing>`, if present, is also called.
437437

438438
Init-only variables without default values, if any exist, must be
439439
specified on the call to :func:`replace` so that they can be passed to
440-
:meth:`__init__` and :meth:`__post_init__`.
440+
:meth:`~object.__init__` and :ref:`__post_init__ <post-init-processing>`.
441441

442442
It is an error for ``changes`` to contain any fields that are
443443
defined as having ``init=False``. A :exc:`ValueError` will be raised
444444
in this case.
445445

446446
Be forewarned about how ``init=False`` fields work during a call to
447447
:func:`replace`. They are not copied from the source object, but
448-
rather are initialized in :meth:`__post_init__`, if they're
448+
rather are initialized in :ref:`__post_init__ <post-init-processing>`, if they're
449449
initialized at all. It is expected that ``init=False`` fields will
450450
be rarely and judiciously used. If they are used, it might be wise
451451
to have alternate class constructors, or perhaps a custom
@@ -476,7 +476,7 @@ Module contents
476476
:const:`KW_ONLY` is otherwise completely ignored. This includes the
477477
name of such a field. By convention, a name of ``_`` is used for a
478478
:const:`KW_ONLY` field. Keyword-only fields signify
479-
:meth:`__init__` parameters that must be specified as keywords when
479+
:meth:`~object.__init__` parameters that must be specified as keywords when
480480
the class is instantiated.
481481

482482
In this example, the fields ``y`` and ``z`` will be marked as keyword-only fields::
@@ -497,20 +497,22 @@ Module contents
497497

498498
.. exception:: FrozenInstanceError
499499

500-
Raised when an implicitly defined :meth:`__setattr__` or
501-
:meth:`__delattr__` is called on a dataclass which was defined with
500+
Raised when an implicitly defined :meth:`~object.__setattr__` or
501+
:meth:`~object.__delattr__` is called on a dataclass which was defined with
502502
``frozen=True``. It is a subclass of :exc:`AttributeError`.
503503

504+
.. _post-init-processing:
505+
504506
Post-init processing
505507
--------------------
506508

507-
The generated :meth:`__init__` code will call a method named
508-
:meth:`__post_init__`, if :meth:`__post_init__` is defined on the
509+
The generated :meth:`~object.__init__` code will call a method named
510+
:meth:`!__post_init__`, if :meth:`!__post_init__` is defined on the
509511
class. It will normally be called as ``self.__post_init__()``.
510512
However, if any ``InitVar`` fields are defined, they will also be
511-
passed to :meth:`__post_init__` in the order they were defined in the
512-
class. If no :meth:`__init__` method is generated, then
513-
:meth:`__post_init__` will not automatically be called.
513+
passed to :meth:`!__post_init__` in the order they were defined in the
514+
class. If no :meth:`~object.__init__` method is generated, then
515+
:meth:`!__post_init__` will not automatically be called.
514516

515517
Among other uses, this allows for initializing field values that
516518
depend on one or more other fields. For example::
@@ -524,10 +526,10 @@ depend on one or more other fields. For example::
524526
def __post_init__(self):
525527
self.c = self.a + self.b
526528

527-
The :meth:`__init__` method generated by :func:`dataclass` does not call base
528-
class :meth:`__init__` methods. If the base class has an :meth:`__init__` method
529+
The :meth:`~object.__init__` method generated by :func:`dataclass` does not call base
530+
class :meth:`~object.__init__` methods. If the base class has an :meth:`~object.__init__` method
529531
that has to be called, it is common to call this method in a
530-
:meth:`__post_init__` method::
532+
:meth:`!__post_init__` method::
531533

532534
@dataclass
533535
class Rectangle:
@@ -541,12 +543,12 @@ that has to be called, it is common to call this method in a
541543
def __post_init__(self):
542544
super().__init__(self.side, self.side)
543545

544-
Note, however, that in general the dataclass-generated :meth:`__init__` methods
546+
Note, however, that in general the dataclass-generated :meth:`~object.__init__` methods
545547
don't need to be called, since the derived dataclass will take care of
546548
initializing all fields of any base class that is a dataclass itself.
547549

548550
See the section below on init-only variables for ways to pass
549-
parameters to :meth:`__post_init__`. Also see the warning about how
551+
parameters to :meth:`!__post_init__`. Also see the warning about how
550552
:func:`replace` handles ``init=False`` fields.
551553

552554
Class variables
@@ -569,8 +571,8 @@ if the type of a field is of type ``dataclasses.InitVar``. If a field
569571
is an ``InitVar``, it is considered a pseudo-field called an init-only
570572
field. As it is not a true field, it is not returned by the
571573
module-level :func:`fields` function. Init-only fields are added as
572-
parameters to the generated :meth:`__init__` method, and are passed to
573-
the optional :meth:`__post_init__` method. They are not otherwise used
574+
parameters to the generated :meth:`~object.__init__` method, and are passed to
575+
the optional :ref:`__post_init__ <post-init-processing>` method. They are not otherwise used
574576
by dataclasses.
575577

576578
For example, suppose a field will be initialized from a database, if a
@@ -597,12 +599,12 @@ Frozen instances
597599
It is not possible to create truly immutable Python objects. However,
598600
by passing ``frozen=True`` to the :meth:`dataclass` decorator you can
599601
emulate immutability. In that case, dataclasses will add
600-
:meth:`__setattr__` and :meth:`__delattr__` methods to the class. These
602+
:meth:`~object.__setattr__` and :meth:`~object.__delattr__` methods to the class. These
601603
methods will raise a :exc:`FrozenInstanceError` when invoked.
602604

603605
There is a tiny performance penalty when using ``frozen=True``:
604-
:meth:`__init__` cannot use simple assignment to initialize fields, and
605-
must use :meth:`object.__setattr__`.
606+
:meth:`~object.__init__` cannot use simple assignment to initialize fields, and
607+
must use :meth:`~object.__setattr__`.
606608

607609
Inheritance
608610
-----------
@@ -630,14 +632,14 @@ example::
630632
The final list of fields is, in order, ``x``, ``y``, ``z``. The final
631633
type of ``x`` is ``int``, as specified in class ``C``.
632634

633-
The generated :meth:`__init__` method for ``C`` will look like::
635+
The generated :meth:`~object.__init__` method for ``C`` will look like::
634636

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

637-
Re-ordering of keyword-only parameters in :meth:`__init__`
638-
----------------------------------------------------------
639+
Re-ordering of keyword-only parameters in :meth:`~object.__init__`
640+
------------------------------------------------------------------
639641

640-
After the parameters needed for :meth:`__init__` are computed, any
642+
After the parameters needed for :meth:`~object.__init__` are computed, any
641643
keyword-only parameters are moved to come after all regular
642644
(non-keyword-only) parameters. This is a requirement of how
643645
keyword-only parameters are implemented in Python: they must come
@@ -658,7 +660,7 @@ fields, and ``Base.x`` and ``D.z`` are regular fields::
658660
z: int = 10
659661
t: int = field(kw_only=True, default=0)
660662

661-
The generated :meth:`__init__` method for ``D`` will look like::
663+
The generated :meth:`~object.__init__` method for ``D`` will look like::
662664

663665
def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, w: int = 1, t: int = 0):
664666

@@ -667,7 +669,7 @@ the list of fields: parameters derived from regular fields are
667669
followed by parameters derived from keyword-only fields.
668670

669671
The relative ordering of keyword-only parameters is maintained in the
670-
re-ordered :meth:`__init__` parameter list.
672+
re-ordered :meth:`~object.__init__` parameter list.
671673

672674

673675
Default factory functions
@@ -679,10 +681,10 @@ example, to create a new instance of a list, use::
679681

680682
mylist: list = field(default_factory=list)
681683

682-
If a field is excluded from :meth:`__init__` (using ``init=False``)
684+
If a field is excluded from :meth:`~object.__init__` (using ``init=False``)
683685
and the field also specifies ``default_factory``, then the default
684686
factory function will always be called from the generated
685-
:meth:`__init__` function. This happens because there is no other
687+
:meth:`~object.__init__` function. This happens because there is no other
686688
way to give the field an initial value.
687689

688690
Mutable default values

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.