From 64365d0df97cbf6c9d75f95234ffb16188e85a18 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 28 Jun 2022 03:10:42 -0700 Subject: [PATCH] gh-91860: Add docs for typing.dataclass_transform field specifier params (GH-94354) (GH-94372) (cherry picked from commit 81ac9ac4921c57c8f31464fed575ea0cfe84df70) Co-authored-by: Erik De Bonte --- Doc/library/typing.rst | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index c7c5536a64fb41..ddcdc70939f19a 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -84,6 +84,8 @@ annotations. These include: *Introducing* :data:`Self` * :pep:`675`: Arbitrary Literal String Type *Introducing* :data:`LiteralString` +* :pep:`681`: Data Class Transforms + *Introducing* the :func:`@dataclass_transform` decorator .. _type-aliases: @@ -2528,7 +2530,17 @@ Functions and decorators For example, type checkers will assume these classes have ``__init__`` methods that accept ``id`` and ``name``. - The arguments to this decorator can be used to customize this behavior: + The decorated class, metaclass, or function may accept the following bool + arguments which type checkers will assume have the same effect as they + would have on the + :func:`@dataclasses.dataclass` decorator: ``init``, + ``eq``, ``order``, ``unsafe_hash``, ``frozen``, ``match_args``, + ``kw_only``, and ``slots``. It must be possible for the value of these + arguments (``True`` or ``False``) to be statically evaluated. + + The arguments to the ``dataclass_transform`` decorator can be used to + customize the default behaviors of the decorated class, metaclass, or + function: * ``eq_default`` indicates whether the ``eq`` parameter is assumed to be ``True`` or ``False`` if it is omitted by the caller. @@ -2541,6 +2553,28 @@ Functions and decorators * Arbitrary other keyword arguments are accepted in order to allow for possible future extensions. + Type checkers recognize the following optional arguments on field + specifiers: + + * ``init`` indicates whether the field should be included in the + synthesized ``__init__`` method. If unspecified, ``init`` defaults to + ``True``. + * ``default`` provides the default value for the field. + * ``default_factory`` provides a runtime callback that returns the + default value for the field. If neither ``default`` nor + ``default_factory`` are specified, the field is assumed to have no + default value and must be provided a value when the class is + instantiated. + * ``factory`` is an alias for ``default_factory``. + * ``kw_only`` indicates whether the field should be marked as + keyword-only. If ``True``, the field will be keyword-only. If + ``False``, it will not be keyword-only. If unspecified, the value of + the ``kw_only`` parameter on the object decorated with + ``dataclass_transform`` will be used, or if that is unspecified, the + value of ``kw_only_default`` on ``dataclass_transform`` will be used. + * ``alias`` provides an alternative name for the field. This alternative + name is used in the synthesized ``__init__`` method. + At runtime, this decorator records its arguments in the ``__dataclass_transform__`` attribute on the decorated object. It has no other runtime effect.