From 2f59a767bcf5bfd51cfe712b35f8eb9b3ea08e2f Mon Sep 17 00:00:00 2001 From: "Eric V. Smith" Date: Sat, 1 May 2021 19:51:12 -0400 Subject: Improve the dataclasses kw_only documentation. (GH-25799) --- Doc/library/dataclasses.rst | 41 ++++++++++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/Doc/library/dataclasses.rst b/Doc/library/dataclasses.rst index dbbc5d6..3808eba 100644 --- a/Doc/library/dataclasses.rst +++ b/Doc/library/dataclasses.rst @@ -169,9 +169,13 @@ Module-level decorators, classes, and functions ``__match_args__`` will not be generated. - ``kw_only``: If true (the default value is ``False``), then all - fields will be marked as keyword-only. See the :term:`parameter` - glossary entry for details. Also see the ``dataclasses.KW_ONLY`` - section. + fields will be marked as keyword-only. If a field is marked as + keyword-only, then the only affect is that the :meth:`__init__` + parameter generated from a keyword-only field must be specified + 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 + ``dataclasses.KW_ONLY`` section. - ``slots``: If true (the default is ``False``), :attr:`__slots__` attribute will be generated and new class will be returned instead of the original one. @@ -195,7 +199,7 @@ Module-level decorators, classes, and functions follows a field with a default value. This is true either when this occurs in a single class, or as a result of class inheritance. -.. function:: field(*, default=MISSING, default_factory=MISSING, repr=True, hash=None, init=True, compare=True, metadata=None) +.. function:: field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING): For common and simple use cases, no other functionality is required. There are, however, some dataclass features that @@ -234,10 +238,6 @@ Module-level decorators, classes, and functions - ``repr``: If true (the default), this field is included in the string returned by the generated :meth:`__repr__` method. - - ``compare``: If true (the default), this field is included in the - generated equality and comparison methods (:meth:`__eq__`, - :meth:`__gt__`, et al.). - - ``hash``: This can be a bool or ``None``. If true, this field is included in the generated :meth:`__hash__` method. If ``None`` (the default), use the value of ``compare``: this would normally be @@ -251,6 +251,10 @@ Module-level decorators, classes, and functions fields that contribute to the type's hash value. Even if a field is excluded from the hash, it will still be used for comparisons. + - ``compare``: If true (the default), this field is included in the + generated equality and comparison methods (:meth:`__eq__`, + :meth:`__gt__`, et al.). + - ``metadata``: This can be a mapping or None. None is treated as an empty dict. This value is wrapped in :func:`~types.MappingProxyType` to make it read-only, and exposed @@ -259,6 +263,10 @@ Module-level decorators, classes, and functions Multiple third-parties can each have their own key, to use as a namespace in the metadata. + - ``kw_only``: If true, this field will be marked as keyword-only. + This is used when the generated :meth:`__init__` method's + parameters are computed. + If the default value of a field is specified by a call to :func:`field()`, then the class attribute for this field will be replaced by the specified ``default`` value. If no ``default`` is @@ -532,15 +540,18 @@ The generated :meth:`__init__` method for ``C`` will look like:: Re-ordering of keyword-only parameters in __init__ -------------------------------------------------- -After the fields needed for :meth:`__init__` are computed, any -keyword-only fields are put after regular fields. In this example, -``Base.y`` and ``D.t`` are keyword-only fields:: +After the parameters needed for :meth:`__init__` are computed, any +keyword-only parameters are moved to come after regular +(non-keyword-only) fields. In this example, ``Base.y``, ``Base.w``, +and ``D.t`` are keyword-only fields, and ``Base.x`` and ``D.z`` are +regular fields:: @dataclass class Base: x: Any = 15.0 _: KW_ONLY y: int = 0 + w: int = 1 @dataclass class D(Base): @@ -549,9 +560,13 @@ keyword-only fields are put after regular fields. In this example, The generated :meth:`__init__` method for ``D`` will look like:: - def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, t: int = 0): + def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, w: int = 1, t: int = 0): + +Note that the parameters have been re-ordered from how they appear in +the list of fields: parameters derived from regular fields are +followed by parameters derived from keyword-only fields. -The relative ordering of keyword-only arguments is not changed from +The relative ordering of keyword-only parameters is not changed from the order they are in computed field :meth:`__init__` list. -- cgit v0.12