Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit 006a453

Browse filesBrowse files
authored
Improve docs for typing.dataclass_transform (#105792)
1 parent 10bf2cd commit 006a453
Copy full SHA for 006a453

File tree

Expand file treeCollapse file tree

1 file changed

+69
-37
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+69
-37
lines changed

‎Doc/library/typing.rst

Copy file name to clipboardExpand all lines: Doc/library/typing.rst
+69-37Lines changed: 69 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -2539,16 +2539,19 @@ Functions and decorators
25392539

25402540
.. versionadded:: 3.11
25412541

2542-
.. decorator:: dataclass_transform
2542+
.. decorator:: dataclass_transform(*, eq_default=True, order_default=False, \
2543+
kw_only_default=False, frozen_default=False, \
2544+
field_specifiers=(), **kwargs)
25432545
25442546
Decorator to mark an object as providing
2545-
:func:`~dataclasses.dataclass`-like behavior.
2547+
:func:`dataclass <dataclasses.dataclass>`-like behavior.
25462548

25472549
``dataclass_transform`` may be used to
25482550
decorate a class, metaclass, or a function that is itself a decorator.
25492551
The presence of ``@dataclass_transform()`` tells a static type checker that the
25502552
decorated object performs runtime "magic" that
2551-
transforms a class in a similar way to :func:`dataclasses.dataclass`.
2553+
transforms a class in a similar way to
2554+
:func:`@dataclasses.dataclass <dataclasses.dataclass>`.
25522555

25532556
Example usage with a decorator function:
25542557

@@ -2602,42 +2605,71 @@ Functions and decorators
26022605
customize the default behaviors of the decorated class, metaclass, or
26032606
function:
26042607

2605-
* ``eq_default`` indicates whether the ``eq`` parameter is assumed to be
2606-
``True`` or ``False`` if it is omitted by the caller.
2607-
* ``order_default`` indicates whether the ``order`` parameter is
2608-
assumed to be True or False if it is omitted by the caller.
2609-
* ``kw_only_default`` indicates whether the ``kw_only`` parameter is
2610-
assumed to be True or False if it is omitted by the caller.
2611-
* ``frozen_default`` indicates whether the ``frozen`` parameter is
2612-
assumed to be True or False if it is omitted by the caller.
2613-
2614-
.. versionadded:: 3.12
2615-
* ``field_specifiers`` specifies a static list of supported classes
2616-
or functions that describe fields, similar to ``dataclasses.field()``.
2617-
* Arbitrary other keyword arguments are accepted in order to allow for
2618-
possible future extensions.
2619-
2620-
Type checkers recognize the following optional arguments on field
2608+
:param bool eq_default:
2609+
Indicates whether the ``eq`` parameter is assumed to be
2610+
``True`` or ``False`` if it is omitted by the caller.
2611+
Defaults to ``True``.
2612+
2613+
:param bool order_default:
2614+
Indicates whether the ``order`` parameter is
2615+
assumed to be ``True`` or ``False`` if it is omitted by the caller.
2616+
Defaults to ``False``.
2617+
2618+
:param bool kw_only_default:
2619+
Indicates whether the ``kw_only`` parameter is
2620+
assumed to be ``True`` or ``False`` if it is omitted by the caller.
2621+
Defaults to ``False``.
2622+
2623+
:param bool frozen_default:
2624+
Indicates whether the ``frozen`` parameter is
2625+
assumed to be ``True`` or ``False`` if it is omitted by the caller.
2626+
Defaults to ``False``.
2627+
2628+
.. versionadded:: 3.12
2629+
2630+
:param field_specifiers:
2631+
Specifies a static list of supported classes
2632+
or functions that describe fields, similar to :func:`dataclasses.field`.
2633+
Defaults to ``()``.
2634+
:type field_specifiers: tuple[Callable[..., Any], ...]
2635+
2636+
:param Any \**kwargs:
2637+
Arbitrary other keyword arguments are accepted in order to allow for
2638+
possible future extensions.
2639+
2640+
Type checkers recognize the following optional parameters on field
26212641
specifiers:
26222642

2623-
* ``init`` indicates whether the field should be included in the
2624-
synthesized ``__init__`` method. If unspecified, ``init`` defaults to
2625-
``True``.
2626-
* ``default`` provides the default value for the field.
2627-
* ``default_factory`` provides a runtime callback that returns the
2628-
default value for the field. If neither ``default`` nor
2629-
``default_factory`` are specified, the field is assumed to have no
2630-
default value and must be provided a value when the class is
2631-
instantiated.
2632-
* ``factory`` is an alias for ``default_factory``.
2633-
* ``kw_only`` indicates whether the field should be marked as
2634-
keyword-only. If ``True``, the field will be keyword-only. If
2635-
``False``, it will not be keyword-only. If unspecified, the value of
2636-
the ``kw_only`` parameter on the object decorated with
2637-
``dataclass_transform`` will be used, or if that is unspecified, the
2638-
value of ``kw_only_default`` on ``dataclass_transform`` will be used.
2639-
* ``alias`` provides an alternative name for the field. This alternative
2640-
name is used in the synthesized ``__init__`` method.
2643+
.. list-table:: **Recognised parameters for field specifiers**
2644+
:header-rows: 1
2645+
:widths: 20 80
2646+
2647+
* - Parameter name
2648+
- Description
2649+
* - ``init``
2650+
- Indicates whether the field should be included in the
2651+
synthesized ``__init__`` method. If unspecified, ``init`` defaults to
2652+
``True``.
2653+
* - ``default``
2654+
- Provides the default value for the field.
2655+
* - ``default_factory``
2656+
- Provides a runtime callback that returns the
2657+
default value for the field. If neither ``default`` nor
2658+
``default_factory`` are specified, the field is assumed to have no
2659+
default value and must be provided a value when the class is
2660+
instantiated.
2661+
* - ``factory``
2662+
- An alias for the ``default_factory`` parameter on field specifiers.
2663+
* - ``kw_only``
2664+
- Indicates whether the field should be marked as
2665+
keyword-only. If ``True``, the field will be keyword-only. If
2666+
``False``, it will not be keyword-only. If unspecified, the value of
2667+
the ``kw_only`` parameter on the object decorated with
2668+
``dataclass_transform`` will be used, or if that is unspecified, the
2669+
value of ``kw_only_default`` on ``dataclass_transform`` will be used.
2670+
* - ``alias``
2671+
- Provides an alternative name for the field. This alternative
2672+
name is used in the synthesized ``__init__`` method.
26412673

26422674
At runtime, this decorator records its arguments in the
26432675
``__dataclass_transform__`` attribute on the decorated object.

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.