[Python-checkins] gh-91860: Add docs for typing.dataclass_transform field specifier params (GH-94354) (GH-94372)

[ambv]

https://github.com/python/cpython/commit/64365d0df97cbf6c9d75f95234ffb16188e85a18
commit: 64365d0df97cbf6c9d75f95234ffb16188e85a18
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2022-06-28T12:10:42+02:00
summary:

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 <erikd at microsoft.com>

files:
M Doc/library/typing.rst

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index c7c5536a64fb4..ddcdc70939f19 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<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<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.