[Python-checkins] Improve docs for `typing.dataclass_transform` (#105792)
AlexWaygood
webhook-mailer at python.org
Thu Jun 15 01:51:46 EDT 2023
https://github.com/python/cpython/commit/006a4532058f1fadba93283c0f45b0d82735b364
commit: 006a4532058f1fadba93283c0f45b0d82735b364
branch: main
author: Alex Waygood <Alex.Waygood at Gmail.com>
committer: AlexWaygood <Alex.Waygood at Gmail.com>
date: 2023-06-15T06:51:42+01:00
summary:
Improve docs for `typing.dataclass_transform` (#105792)
files:
M Doc/library/typing.rst
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 73555d54115f..859700e0c69b 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -2539,16 +2539,19 @@ Functions and decorators
.. versionadded:: 3.11
-.. decorator:: dataclass_transform
+.. decorator:: dataclass_transform(*, eq_default=True, order_default=False, \
+ kw_only_default=False, frozen_default=False, \
+ field_specifiers=(), **kwargs)
Decorator to mark an object as providing
- :func:`~dataclasses.dataclass`-like behavior.
+ :func:`dataclass <dataclasses.dataclass>`-like behavior.
``dataclass_transform`` may be used to
decorate a class, metaclass, or a function that is itself a decorator.
The presence of ``@dataclass_transform()`` tells a static type checker that the
decorated object performs runtime "magic" that
- transforms a class in a similar way to :func:`dataclasses.dataclass`.
+ transforms a class in a similar way to
+ :func:`@dataclasses.dataclass <dataclasses.dataclass>`.
Example usage with a decorator function:
@@ -2602,42 +2605,71 @@ Functions and decorators
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.
- * ``order_default`` indicates whether the ``order`` parameter is
- assumed to be True or False if it is omitted by the caller.
- * ``kw_only_default`` indicates whether the ``kw_only`` parameter is
- assumed to be True or False if it is omitted by the caller.
- * ``frozen_default`` indicates whether the ``frozen`` parameter is
- assumed to be True or False if it is omitted by the caller.
-
- .. versionadded:: 3.12
- * ``field_specifiers`` specifies a static list of supported classes
- or functions that describe fields, similar to ``dataclasses.field()``.
- * Arbitrary other keyword arguments are accepted in order to allow for
- possible future extensions.
-
- Type checkers recognize the following optional arguments on field
+ :param bool eq_default:
+ Indicates whether the ``eq`` parameter is assumed to be
+ ``True`` or ``False`` if it is omitted by the caller.
+ Defaults to ``True``.
+
+ :param bool order_default:
+ Indicates whether the ``order`` parameter is
+ assumed to be ``True`` or ``False`` if it is omitted by the caller.
+ Defaults to ``False``.
+
+ :param bool kw_only_default:
+ Indicates whether the ``kw_only`` parameter is
+ assumed to be ``True`` or ``False`` if it is omitted by the caller.
+ Defaults to ``False``.
+
+ :param bool frozen_default:
+ Indicates whether the ``frozen`` parameter is
+ assumed to be ``True`` or ``False`` if it is omitted by the caller.
+ Defaults to ``False``.
+
+ .. versionadded:: 3.12
+
+ :param field_specifiers:
+ Specifies a static list of supported classes
+ or functions that describe fields, similar to :func:`dataclasses.field`.
+ Defaults to ``()``.
+ :type field_specifiers: tuple[Callable[..., Any], ...]
+
+ :param Any \**kwargs:
+ Arbitrary other keyword arguments are accepted in order to allow for
+ possible future extensions.
+
+ Type checkers recognize the following optional parameters 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.
+ .. list-table:: **Recognised parameters for field specifiers**
+ :header-rows: 1
+ :widths: 20 80
+
+ * - Parameter name
+ - Description
+ * - ``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``
+ - An alias for the ``default_factory`` parameter on field specifiers.
+ * - ``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.
More information about the Python-checkins
mailing list