mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-27 02:39:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

gh-101100: Add reference doc for __post_init__ (#103818)

Browse source 
Signed-off-by: Olga Matoula <olgamatoula@gmail.com>
This commit is contained in:
Olga Matoula 2023-04-28 13:10:26 -06:00 • committed by GitHub
parent c3453fbb11
commit 83aa496f81
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 23 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

23
Doc/library/dataclasses.rst
View file

@ -437,11 +437,11 @@ Module contents
The newly returned object is created by calling the :meth:`~object.__init__` The newly returned object is created by calling the :meth:`~object.__init__`
method of the dataclass. This ensures that method of the dataclass. This ensures that
:ref:`__post_init__ <post-init-processing>`, if present, is also called. :meth:`__post_init__`, if present, is also called.
Init-only variables without default values, if any exist, must be Init-only variables without default values, if any exist, must be
specified on the call to :func:`replace` so that they can be passed to specified on the call to :func:`replace` so that they can be passed to
:meth:`~object.__init__` and :ref:`__post_init__ <post-init-processing>`. :meth:`~object.__init__` and :meth:`__post_init__`.
It is an error for ``changes`` to contain any fields that are It is an error for ``changes`` to contain any fields that are
defined as having ``init=False``. A :exc:`ValueError` will be raised defined as having ``init=False``. A :exc:`ValueError` will be raised
@ -449,7 +449,7 @@ Module contents
Be forewarned about how ``init=False`` fields work during a call to Be forewarned about how ``init=False`` fields work during a call to
:func:`replace`. They are not copied from the source object, but :func:`replace`. They are not copied from the source object, but
rather are initialized in :ref:`__post_init__ <post-init-processing>`, if they're rather are initialized in :meth:`__post_init__`, if they're
initialized at all. It is expected that ``init=False`` fields will initialized at all. It is expected that ``init=False`` fields will
be rarely and judiciously used. If they are used, it might be wise be rarely and judiciously used. If they are used, it might be wise
to have alternate class constructors, or perhaps a custom to have alternate class constructors, or perhaps a custom
@ -510,13 +510,14 @@ Module contents
Post-init processing Post-init processing
-------------------- --------------------
The generated :meth:`~object.__init__` code will call a method named .. function:: __post_init__()
:meth:`!__post_init__`, if :meth:`!__post_init__` is defined on the
class. It will normally be called as ``self.__post_init__()``. When defined on the class, it will be called by the generated
:meth:`~object.__init__`, normally as ``self.__post_init__()``.
However, if any ``InitVar`` fields are defined, they will also be However, if any ``InitVar`` fields are defined, they will also be
passed to :meth:`!__post_init__` in the order they were defined in the passed to :meth:`__post_init__` in the order they were defined in the
class. If no :meth:`~object.__init__` method is generated, then class. If no :meth:`~object.__init__` method is generated, then
:meth:`!__post_init__` will not automatically be called. :meth:`__post_init__` will not automatically be called.
Among other uses, this allows for initializing field values that Among other uses, this allows for initializing field values that
depend on one or more other fields. For example:: depend on one or more other fields. For example::
@ -533,7 +534,7 @@ depend on one or more other fields. For example::
The :meth:`~object.__init__` method generated by :func:`dataclass` does not call base The :meth:`~object.__init__` method generated by :func:`dataclass` does not call base
class :meth:`~object.__init__` methods. If the base class has an :meth:`~object.__init__` method class :meth:`~object.__init__` methods. If the base class has an :meth:`~object.__init__` method
that has to be called, it is common to call this method in a that has to be called, it is common to call this method in a
:meth:`!__post_init__` method:: :meth:`__post_init__` method::
@dataclass @dataclass
class Rectangle: class Rectangle:
@ -552,7 +553,7 @@ don't need to be called, since the derived dataclass will take care of
initializing all fields of any base class that is a dataclass itself. initializing all fields of any base class that is a dataclass itself.
See the section below on init-only variables for ways to pass See the section below on init-only variables for ways to pass
parameters to :meth:`!__post_init__`. Also see the warning about how parameters to :meth:`__post_init__`. Also see the warning about how
:func:`replace` handles ``init=False`` fields. :func:`replace` handles ``init=False`` fields.
Class variables Class variables
@ -576,7 +577,7 @@ is an ``InitVar``, it is considered a pseudo-field called an init-only
field. As it is not a true field, it is not returned by the field. As it is not a true field, it is not returned by the
module-level :func:`fields` function. Init-only fields are added as module-level :func:`fields` function. Init-only fields are added as
parameters to the generated :meth:`~object.__init__` method, and are passed to parameters to the generated :meth:`~object.__init__` method, and are passed to
the optional :ref:`__post_init__ <post-init-processing>` method. They are not otherwise used the optional :meth:`__post_init__` method. They are not otherwise used
by dataclasses. by dataclasses.
For example, suppose a field will be initialized from a database, if a For example, suppose a field will be initialized from a database, if a