mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 10:19:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

More clarification of kw_only args. (GH-25838)

Browse source 
Also, clarify that the dataclass decorator is what raises an error for some mutable defaults.
This commit is contained in:
Eric V. Smith 2021-05-03 01:55:13 -04:00 • committed by GitHub
parent c59baa02b0
commit a21b3d2fa2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 20 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

33
Doc/library/dataclasses.rst
View file

@ -307,8 +307,8 @@ Module contents
- ``type``: The type of the field. - ``type``: The type of the field.
- ``default``, ``default_factory``, ``init``, ``repr``, ``hash``, - ``default``, ``default_factory``, ``init``, ``repr``, ``hash``,
``compare``, and ``metadata`` have the identical meaning and ``compare``, ``metadata``, and ``kw_only`` have the identical
values as they do in the :func:`field` declaration. meaning and values as they do in the :func:`field` declaration.
Other attributes may exist, but they are private and must not be Other attributes may exist, but they are private and must not be
inspected or relied on. inspected or relied on.
@ -459,6 +459,9 @@ Module contents
p = Point(0, y=1.5, z=2.0) 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`.
.. exception:: FrozenInstanceError .. exception:: FrozenInstanceError
Raised when an implicitly defined :meth:`__setattr__` or Raised when an implicitly defined :meth:`__setattr__` or
@ -582,9 +585,12 @@ Re-ordering of keyword-only parameters in :meth:`__init__`
After the parameters needed for :meth:`__init__` are computed, any After the parameters needed for :meth:`__init__` are computed, any
keyword-only parameters are moved to come after all regular keyword-only parameters are moved to come after all regular
(non-keyword-only) parameters. In this example, ``Base.y``, (non-keyword-only) parameters. This is a requirement of how
``Base.w``, and ``D.t`` are keyword-only fields, and ``Base.x`` and keyword-only parameters are implemented in Python: they must come
``D.z`` are regular fields:: after non-keyword-only parameters.
In this example, ``Base.y``, ``Base.w``, and ``D.t`` are keyword-only
fields, and ``Base.x`` and ``D.z`` are regular fields::
@dataclass @dataclass
class Base: class Base:
@ -666,14 +672,15 @@ Mutable default values
assert D().x is D().x assert D().x is D().x
This has the same issue as the original example using class ``C``. This has the same issue as the original example using class ``C``.
That is, two instances of class ``D`` that do not specify a value for That is, two instances of class ``D`` that do not specify a value
``x`` when creating a class instance will share the same copy of for ``x`` when creating a class instance will share the same copy
``x``. Because dataclasses just use normal Python class creation of ``x``. Because dataclasses just use normal Python class
they also share this behavior. There is no general way for Data creation they also share this behavior. There is no general way
Classes to detect this condition. Instead, dataclasses will raise a for Data Classes to detect this condition. Instead, the
:exc:`TypeError` if it detects a default parameter of type ``list``, :func:`dataclass` decorator will raise a :exc:`TypeError` if it
``dict``, or ``set``. This is a partial solution, but it does protect detects a default parameter of type ``list``, ``dict``, or ``set``.
against many common errors. This is a partial solution, but it does protect against many common
errors.
Using default factory functions is a way to create new instances of Using default factory functions is a way to create new instances of
mutable types as default values for fields:: mutable types as default values for fields::