mirror of https://github.com/python/cpython
docs: fix over-linking in dataclasses.rst (#117005)
This commit is contained in:
Ned Batchelder
GitHub
parent
570a82d46a
commit
0907871d43
|
|
@ -1,5 +1,5 @@
|
|||
:mod:`dataclasses` --- Data Classes
|
||||
===================================
|
||||
:mod:`!dataclasses` --- Data Classes
|
||||
====================================
|
||||
|
||||
.. module:: dataclasses
|
||||
:synopsis: Generate special methods on user-defined classes.
|
||||
|
|
@ -31,7 +31,7 @@ using :pep:`526` type annotations. For example, this code::
|
|||
def total_cost(self) -> float:
|
||||
return self.unit_price * self.quantity_on_hand
|
||||
|
||||
will add, among other things, a :meth:`~object.__init__` that looks like::
|
||||
will add, among other things, a :meth:`!__init__` that looks like::
|
||||
|
||||
def __init__(self, name: str, unit_price: float, quantity_on_hand: int = 0):
|
||||
self.name = name
|
||||
|
|
@ -49,26 +49,26 @@ Module contents
|
|||
.. 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)
|
||||
|
||||
This function is a :term:`decorator` that is used to add generated
|
||||
:term:`special method`\s to classes, as described below.
|
||||
:term:`special methods <special method>` to classes, as described below.
|
||||
|
||||
The :func:`dataclass` decorator examines the class to find
|
||||
The ``@dataclass`` decorator examines the class to find
|
||||
``field``\s. A ``field`` is defined as a class variable that has a
|
||||
:term:`type annotation <variable annotation>`. With two
|
||||
exceptions described below, nothing in :func:`dataclass`
|
||||
exceptions described below, nothing in ``@dataclass``
|
||||
examines the type specified in the variable annotation.
|
||||
|
||||
The order of the fields in all of the generated methods is the
|
||||
order in which they appear in the class definition.
|
||||
|
||||
The :func:`dataclass` decorator will add various "dunder" methods to
|
||||
The ``@dataclass`` decorator will add various "dunder" methods to
|
||||
the class, described below. If any of the added methods already
|
||||
exist in the class, the behavior depends on the parameter, as documented
|
||||
below. The decorator returns the same class that it is called on; no new
|
||||
class is created.
|
||||
|
||||
If :func:`dataclass` is used just as a simple decorator with no parameters,
|
||||
If ``@dataclass`` is used just as a simple decorator with no parameters,
|
||||
it acts as if it has the default values documented in this
|
||||
signature. That is, these three uses of :func:`dataclass` are
|
||||
signature. That is, these three uses of ``@dataclass`` are
|
||||
equivalent::
|
||||
|
||||
@dataclass
|
||||
|
|
@ -84,12 +84,12 @@ Module contents
|
|||
class C:
|
||||
...
|
||||
|
||||
The parameters to :func:`dataclass` are:
|
||||
The parameters to ``@dataclass`` are:
|
||||
|
||||
- ``init``: If true (the default), a :meth:`~object.__init__` method will be
|
||||
generated.
|
||||
|
||||
If the class already defines :meth:`~object.__init__`, this parameter is
|
||||
If the class already defines :meth:`!__init__`, this parameter is
|
||||
ignored.
|
||||
|
||||
- ``repr``: If true (the default), a :meth:`~object.__repr__` method will be
|
||||
|
|
@ -99,7 +99,7 @@ Module contents
|
|||
are not included. For example:
|
||||
``InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10)``.
|
||||
|
||||
If the class already defines :meth:`~object.__repr__`, this parameter is
|
||||
If the class already defines :meth:`!__repr__`, this parameter is
|
||||
ignored.
|
||||
|
||||
- ``eq``: If true (the default), an :meth:`~object.__eq__` method will be
|
||||
|
|
@ -107,7 +107,7 @@ Module contents
|
|||
of its fields, in order. Both instances in the comparison must
|
||||
be of the identical type.
|
||||
|
||||
If the class already defines :meth:`~object.__eq__`, this parameter is
|
||||
If the class already defines :meth:`!__eq__`, this parameter is
|
||||
ignored.
|
||||
|
||||
- ``order``: If true (the default is ``False``), :meth:`~object.__lt__`,
|
||||
|
|
@ -117,43 +117,43 @@ Module contents
|
|||
identical type. If ``order`` is true and ``eq`` is false, a
|
||||
:exc:`ValueError` is raised.
|
||||
|
||||
If the class already defines any of :meth:`~object.__lt__`,
|
||||
:meth:`~object.__le__`, :meth:`~object.__gt__`, or :meth:`~object.__ge__`, then
|
||||
If the class already defines any of :meth:`!__lt__`,
|
||||
:meth:`!__le__`, :meth:`!__gt__`, or :meth:`!__ge__`, then
|
||||
:exc:`TypeError` is raised.
|
||||
|
||||
- ``unsafe_hash``: If ``False`` (the default), a :meth:`~object.__hash__` method
|
||||
is generated according to how ``eq`` and ``frozen`` are set.
|
||||
|
||||
:meth:`~object.__hash__` is used by built-in :meth:`hash()`, and when objects are
|
||||
:meth:`!__hash__` is used by built-in :meth:`hash()`, and when objects are
|
||||
added to hashed collections such as dictionaries and sets. Having a
|
||||
:meth:`~object.__hash__` implies that instances of the class are immutable.
|
||||
:meth:`!__hash__` implies that instances of the class are immutable.
|
||||
Mutability is a complicated property that depends on the programmer's
|
||||
intent, the existence and behavior of :meth:`~object.__eq__`, and the values of
|
||||
the ``eq`` and ``frozen`` flags in the :func:`dataclass` decorator.
|
||||
intent, the existence and behavior of :meth:`!__eq__`, and the values of
|
||||
the ``eq`` and ``frozen`` flags in the ``@dataclass`` decorator.
|
||||
|
||||
By default, :func:`dataclass` will not implicitly add a :meth:`~object.__hash__`
|
||||
By default, ``@dataclass`` will not implicitly add a :meth:`~object.__hash__`
|
||||
method unless it is safe to do so. Neither will it add or change an
|
||||
existing explicitly defined :meth:`~object.__hash__` method. Setting the class
|
||||
existing explicitly defined :meth:`!__hash__` method. Setting the class
|
||||
attribute ``__hash__ = None`` has a specific meaning to Python, as
|
||||
described in the :meth:`~object.__hash__` documentation.
|
||||
described in the :meth:`!__hash__` documentation.
|
||||
|
||||
If :meth:`~object.__hash__` is not explicitly defined, or if it is set to ``None``,
|
||||
then :func:`dataclass` *may* add an implicit :meth:`~object.__hash__` method.
|
||||
Although not recommended, you can force :func:`dataclass` to create a
|
||||
:meth:`~object.__hash__` method with ``unsafe_hash=True``. This might be the case
|
||||
If :meth:`!__hash__` is not explicitly defined, or if it is set to ``None``,
|
||||
then ``@dataclass`` *may* add an implicit :meth:`!__hash__` method.
|
||||
Although not recommended, you can force ``@dataclass`` to create a
|
||||
:meth:`!__hash__` method with ``unsafe_hash=True``. This might be the case
|
||||
if your class is logically immutable but can still be mutated.
|
||||
This is a specialized use case and should be considered carefully.
|
||||
|
||||
Here are the rules governing implicit creation of a :meth:`~object.__hash__`
|
||||
method. Note that you cannot both have an explicit :meth:`~object.__hash__`
|
||||
Here are the rules governing implicit creation of a :meth:`!__hash__`
|
||||
method. Note that you cannot both have an explicit :meth:`!__hash__`
|
||||
method in your dataclass and set ``unsafe_hash=True``; this will result
|
||||
in a :exc:`TypeError`.
|
||||
|
||||
If ``eq`` and ``frozen`` are both true, by default :func:`dataclass` will
|
||||
generate a :meth:`~object.__hash__` method for you. If ``eq`` is true and
|
||||
``frozen`` is false, :meth:`~object.__hash__` will be set to ``None``, marking it
|
||||
If ``eq`` and ``frozen`` are both true, by default ``@dataclass`` will
|
||||
generate a :meth:`!__hash__` method for you. If ``eq`` is true and
|
||||
``frozen`` is false, :meth:`!__hash__` will be set to ``None``, marking it
|
||||
unhashable (which it is, since it is mutable). If ``eq`` is false,
|
||||
:meth:`~object.__hash__` will be left untouched meaning the :meth:`~object.__hash__`
|
||||
:meth:`!__hash__` will be left untouched meaning the :meth:`!__hash__`
|
||||
method of the superclass will be used (if the superclass is
|
||||
:class:`object`, this means it will fall back to id-based hashing).
|
||||
|
||||
|
|
@ -165,7 +165,7 @@ Module contents
|
|||
- ``match_args``: If true (the default is ``True``), the
|
||||
``__match_args__`` tuple will be created from the list of
|
||||
parameters to the generated :meth:`~object.__init__` method (even if
|
||||
:meth:`~object.__init__` is not generated, see above). If false, or if
|
||||
:meth:`!__init__` is not generated, see above). If false, or if
|
||||
``__match_args__`` is already defined in the class, then
|
||||
``__match_args__`` will not be generated.
|
||||
|
||||
|
|
@ -175,7 +175,7 @@ Module contents
|
|||
fields will be marked as keyword-only. If a field is marked as
|
||||
keyword-only, then the only effect is that the :meth:`~object.__init__`
|
||||
parameter generated from a keyword-only field must be specified
|
||||
with a keyword when :meth:`~object.__init__` is called. There is no
|
||||
with a keyword when :meth:`!__init__` is called. There is no
|
||||
effect on any other aspect of dataclasses. See the
|
||||
:term:`parameter` glossary entry for details. Also see the
|
||||
:const:`KW_ONLY` section.
|
||||
|
|
@ -184,7 +184,7 @@ Module contents
|
|||
|
||||
- ``slots``: If true (the default is ``False``), :attr:`~object.__slots__` attribute
|
||||
will be generated and new class will be returned instead of the original one.
|
||||
If :attr:`~object.__slots__` is already defined in the class, then :exc:`TypeError`
|
||||
If :attr:`!__slots__` is already defined in the class, then :exc:`TypeError`
|
||||
is raised.
|
||||
|
||||
.. versionadded:: 3.10
|
||||
|
|
@ -229,7 +229,7 @@ Module contents
|
|||
required. There are, however, some dataclass features that
|
||||
require additional per-field information. To satisfy this need for
|
||||
additional information, you can replace the default field value
|
||||
with a call to the provided :func:`field` function. For example::
|
||||
with a call to the provided :func:`!field` function. For example::
|
||||
|
||||
@dataclass
|
||||
class C:
|
||||
|
|
@ -243,10 +243,10 @@ Module contents
|
|||
used because ``None`` is a valid value for some parameters with
|
||||
a distinct meaning. No code should directly use the :const:`MISSING` value.
|
||||
|
||||
The parameters to :func:`field` are:
|
||||
The parameters to :func:`!field` are:
|
||||
|
||||
- ``default``: If provided, this will be the default value for this
|
||||
field. This is needed because the :meth:`field` call itself
|
||||
field. This is needed because the :func:`!field` call itself
|
||||
replaces the normal position of the default value.
|
||||
|
||||
- ``default_factory``: If provided, it must be a zero-argument
|
||||
|
|
@ -293,10 +293,10 @@ Module contents
|
|||
.. versionadded:: 3.10
|
||||
|
||||
If the default value of a field is specified by a call to
|
||||
:func:`field()`, then the class attribute for this field will be
|
||||
:func:`!field`, then the class attribute for this field will be
|
||||
replaced by the specified ``default`` value. If no ``default`` is
|
||||
provided, then the class attribute will be deleted. The intent is
|
||||
that after the :func:`dataclass` decorator runs, the class
|
||||
that after the :func:`@dataclass <dataclass>` decorator runs, the class
|
||||
attributes will all contain the default values for the fields, just
|
||||
as if the default value itself were specified. For example,
|
||||
after::
|
||||
|
|
@ -314,10 +314,10 @@ Module contents
|
|||
|
||||
.. class:: Field
|
||||
|
||||
:class:`Field` objects describe each defined field. These objects
|
||||
:class:`!Field` objects describe each defined field. These objects
|
||||
are created internally, and are returned by the :func:`fields`
|
||||
module-level method (see below). Users should never instantiate a
|
||||
:class:`Field` object directly. Its documented attributes are:
|
||||
:class:`!Field` object directly. Its documented attributes are:
|
||||
|
||||
- ``name``: The name of the field.
|
||||
- ``type``: The type of the field.
|
||||
|
|
@ -343,7 +343,7 @@ Module contents
|
|||
lists, and tuples are recursed into. Other objects are copied with
|
||||
:func:`copy.deepcopy`.
|
||||
|
||||
Example of using :func:`asdict` on nested dataclasses::
|
||||
Example of using :func:`!asdict` on nested dataclasses::
|
||||
|
||||
@dataclass
|
||||
class Point:
|
||||
|
|
@ -364,7 +364,7 @@ Module contents
|
|||
|
||||
dict((field.name, getattr(obj, field.name)) for field in fields(obj))
|
||||
|
||||
:func:`asdict` raises :exc:`TypeError` if ``obj`` is not a dataclass
|
||||
:func:`!asdict` raises :exc:`TypeError` if ``obj`` is not a dataclass
|
||||
instance.
|
||||
|
||||
.. function:: astuple(obj, *, tuple_factory=tuple)
|
||||
|
|
@ -384,7 +384,7 @@ Module contents
|
|||
|
||||
tuple(getattr(obj, field.name) for field in dataclasses.fields(obj))
|
||||
|
||||
:func:`astuple` raises :exc:`TypeError` if ``obj`` is not a dataclass
|
||||
:func:`!astuple` raises :exc:`TypeError` if ``obj`` is not a dataclass
|
||||
instance.
|
||||
|
||||
.. 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)
|
||||
|
|
@ -397,7 +397,7 @@ Module contents
|
|||
``typing.Any`` is used for ``type``. The values of ``init``,
|
||||
``repr``, ``eq``, ``order``, ``unsafe_hash``, ``frozen``,
|
||||
``match_args``, ``kw_only``, ``slots``, and ``weakref_slot`` have
|
||||
the same meaning as they do in :func:`dataclass`.
|
||||
the same meaning as they do in :func:`@dataclass <dataclass>`.
|
||||
|
||||
If ``module`` is defined, the ``__module__`` attribute
|
||||
of the dataclass is set to that value.
|
||||
|
|
@ -405,7 +405,7 @@ Module contents
|
|||
|
||||
This function is not strictly required, because any Python
|
||||
mechanism for creating a new class with ``__annotations__`` can
|
||||
then apply the :func:`dataclass` function to convert that class to
|
||||
then apply the ``@dataclass`` function to convert that class to
|
||||
a dataclass. This function is provided as a convenience. For
|
||||
example::
|
||||
|
||||
|
|
@ -438,15 +438,15 @@ Module contents
|
|||
:meth:`__post_init__`, if present, is also called.
|
||||
|
||||
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
|
||||
:meth:`~object.__init__` and :meth:`__post_init__`.
|
||||
specified on the call to :func:`!replace` so that they can be passed to
|
||||
:meth:`!__init__` and :meth:`__post_init__`.
|
||||
|
||||
It is an error for ``changes`` to contain any fields that are
|
||||
defined as having ``init=False``. A :exc:`ValueError` will be raised
|
||||
in this case.
|
||||
|
||||
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 :meth:`__post_init__`, if they're
|
||||
initialized at all. It is expected that ``init=False`` fields will
|
||||
be rarely and judiciously used. If they are used, it might be wise
|
||||
|
|
@ -475,11 +475,11 @@ Module contents
|
|||
.. data:: KW_ONLY
|
||||
|
||||
A sentinel value used as a type annotation. Any fields after a
|
||||
pseudo-field with the type of :const:`KW_ONLY` are marked as
|
||||
pseudo-field with the type of :const:`!KW_ONLY` are marked as
|
||||
keyword-only fields. Note that a pseudo-field of type
|
||||
:const:`KW_ONLY` is otherwise completely ignored. This includes the
|
||||
:const:`!KW_ONLY` is otherwise completely ignored. This includes the
|
||||
name of such a field. By convention, a name of ``_`` is used for a
|
||||
:const:`KW_ONLY` field. Keyword-only fields signify
|
||||
:const:`!KW_ONLY` field. Keyword-only fields signify
|
||||
:meth:`~object.__init__` parameters that must be specified as keywords when
|
||||
the class is instantiated.
|
||||
|
||||
|
|
@ -495,7 +495,7 @@ Module contents
|
|||
p = Point(0, y=1.5, z=2.0)
|
||||
|
||||
In a single dataclass, it is an error to specify more than one
|
||||
field whose type is :const:`KW_ONLY`.
|
||||
field whose type is :const:`!KW_ONLY`.
|
||||
|
||||
.. versionadded:: 3.10
|
||||
|
||||
|
|
@ -515,9 +515,9 @@ Post-init processing
|
|||
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
|
||||
passed to :meth:`__post_init__` in the order they were defined in the
|
||||
class. If no :meth:`~object.__init__` method is generated, then
|
||||
:meth:`__post_init__` will not automatically be called.
|
||||
passed to :meth:`!__post_init__` in the order they were defined in the
|
||||
class. If no :meth:`!__init__` method is generated, then
|
||||
:meth:`!__post_init__` will not automatically be called.
|
||||
|
||||
Among other uses, this allows for initializing field values that
|
||||
depend on one or more other fields. For example::
|
||||
|
|
@ -531,8 +531,8 @@ Post-init processing
|
|||
def __post_init__(self):
|
||||
self.c = self.a + self.b
|
||||
|
||||
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
|
||||
The :meth:`~object.__init__` method generated by :func:`@dataclass <dataclass>` does not call base
|
||||
class :meth:`!__init__` methods. If the base class has an :meth:`!__init__` method
|
||||
that has to be called, it is common to call this method in a
|
||||
:meth:`__post_init__` method::
|
||||
|
||||
|
|
@ -548,18 +548,18 @@ that has to be called, it is common to call this method in a
|
|||
def __post_init__(self):
|
||||
super().__init__(self.side, self.side)
|
||||
|
||||
Note, however, that in general the dataclass-generated :meth:`~object.__init__` methods
|
||||
Note, however, that in general the dataclass-generated :meth:`!__init__` methods
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Class variables
|
||||
---------------
|
||||
|
||||
One of the few places where :func:`dataclass` actually inspects the type
|
||||
One of the few places where :func:`@dataclass <dataclass>` actually inspects the type
|
||||
of a field is to determine if a field is a class variable as defined
|
||||
in :pep:`526`. It does this by checking if the type of the field is
|
||||
``typing.ClassVar``. If a field is a ``ClassVar``, it is excluded
|
||||
|
|
@ -570,7 +570,7 @@ module-level :func:`fields` function.
|
|||
Init-only variables
|
||||
-------------------
|
||||
|
||||
Another place where :func:`dataclass` inspects a type annotation is to
|
||||
Another place where :func:`@dataclass <dataclass>` inspects a type annotation is to
|
||||
determine if a field is an init-only variable. It does this by seeing
|
||||
if the type of a field is of type ``dataclasses.InitVar``. If a field
|
||||
is an ``InitVar``, it is considered a pseudo-field called an init-only
|
||||
|
|
@ -602,19 +602,19 @@ Frozen instances
|
|||
----------------
|
||||
|
||||
It is not possible to create truly immutable Python objects. However,
|
||||
by passing ``frozen=True`` to the :meth:`dataclass` decorator you can
|
||||
by passing ``frozen=True`` to the :func:`@dataclass <dataclass>` decorator you can
|
||||
emulate immutability. In that case, dataclasses will add
|
||||
:meth:`~object.__setattr__` and :meth:`~object.__delattr__` methods to the class. These
|
||||
methods will raise a :exc:`FrozenInstanceError` when invoked.
|
||||
|
||||
There is a tiny performance penalty when using ``frozen=True``:
|
||||
:meth:`~object.__init__` cannot use simple assignment to initialize fields, and
|
||||
must use :meth:`!object.__setattr__`.
|
||||
must use :meth:`!__setattr__`.
|
||||
|
||||
Inheritance
|
||||
-----------
|
||||
|
||||
When the dataclass is being created by the :meth:`dataclass` decorator,
|
||||
When the dataclass is being created by the :func:`@dataclass <dataclass>` decorator,
|
||||
it looks through all of the class's base classes in reverse MRO (that
|
||||
is, starting at :class:`object`) and, for each dataclass that it finds,
|
||||
adds the fields from that base class to an ordered mapping of fields.
|
||||
|
|
@ -641,8 +641,8 @@ The generated :meth:`~object.__init__` method for ``C`` will look like::
|
|||
|
||||
def __init__(self, x: int = 15, y: int = 0, z: int = 10):
|
||||
|
||||
Re-ordering of keyword-only parameters in :meth:`~object.__init__`
|
||||
------------------------------------------------------------------
|
||||
Re-ordering of keyword-only parameters in :meth:`!__init__`
|
||||
-----------------------------------------------------------
|
||||
|
||||
After the parameters needed for :meth:`~object.__init__` are computed, any
|
||||
keyword-only parameters are moved to come after all regular
|
||||
|
|
@ -665,7 +665,7 @@ fields, and ``Base.x`` and ``D.z`` are regular fields::
|
|||
z: int = 10
|
||||
t: int = field(kw_only=True, default=0)
|
||||
|
||||
The generated :meth:`~object.__init__` method for ``D`` will look like::
|
||||
The generated :meth:`!__init__` method for ``D`` will look like::
|
||||
|
||||
def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, w: int = 1, t: int = 0):
|
||||
|
||||
|
|
@ -674,7 +674,7 @@ the list of fields: parameters derived from regular fields are
|
|||
followed by parameters derived from keyword-only fields.
|
||||
|
||||
The relative ordering of keyword-only parameters is maintained in the
|
||||
re-ordered :meth:`~object.__init__` parameter list.
|
||||
re-ordered :meth:`!__init__` parameter list.
|
||||
|
||||
|
||||
Default factory functions
|
||||
|
|
@ -689,7 +689,7 @@ example, to create a new instance of a list, use::
|
|||
If a field is excluded from :meth:`~object.__init__` (using ``init=False``)
|
||||
and the field also specifies ``default_factory``, then the default
|
||||
factory function will always be called from the generated
|
||||
:meth:`~object.__init__` function. This happens because there is no other
|
||||
:meth:`!__init__` function. This happens because there is no other
|
||||
way to give the field an initial value.
|
||||
|
||||
Mutable default values
|
||||
|
|
@ -738,7 +738,7 @@ for ``x`` when creating a class instance will share the same copy
|
|||
of ``x``. Because dataclasses just use normal Python class
|
||||
creation they also share this behavior. There is no general way
|
||||
for Data Classes to detect this condition. Instead, the
|
||||
:func:`dataclass` decorator will raise a :exc:`ValueError` if it
|
||||
:func:`@dataclass <dataclass>` decorator will raise a :exc:`ValueError` if it
|
||||
detects an unhashable default parameter. The assumption is that if
|
||||
a value is unhashable, it is mutable. This is a partial solution,
|
||||
but it does protect against many common errors.
|
||||
|
|
@ -764,15 +764,17 @@ Descriptor-typed fields
|
|||
Fields that are assigned :ref:`descriptor objects <descriptors>` as their
|
||||
default value have the following special behaviors:
|
||||
|
||||
* The value for the field passed to the dataclass's ``__init__`` method is
|
||||
passed to the descriptor's ``__set__`` method rather than overwriting the
|
||||
* The value for the field passed to the dataclass's :meth:`~object.__init__` method is
|
||||
passed to the descriptor's :meth:`~object.__set__` method rather than overwriting the
|
||||
descriptor object.
|
||||
|
||||
* Similarly, when getting or setting the field, the descriptor's
|
||||
``__get__`` or ``__set__`` method is called rather than returning or
|
||||
:meth:`~object.__get__` or :meth:`!__set__` method is called rather than returning or
|
||||
overwriting the descriptor object.
|
||||
* To determine whether a field contains a default value, ``dataclasses``
|
||||
will call the descriptor's ``__get__`` method using its class access
|
||||
form (i.e. ``descriptor.__get__(obj=None, type=cls)``. If the
|
||||
|
||||
* To determine whether a field contains a default value, :func:`@dataclass <dataclass>`
|
||||
will call the descriptor's :meth:`!__get__` method using its class access
|
||||
form: ``descriptor.__get__(obj=None, type=cls)``. If the
|
||||
descriptor returns a value in this case, it will be used as the
|
||||
field's default. On the other hand, if the descriptor raises
|
||||
:exc:`AttributeError` in this situation, no default value will be
|
||||
|
|
|
|||
Loading…
Reference in New Issue