Skip to content

Commit c197bd8

Browse files
authored
[3.11] Improve docs for typing.dataclass_transform (#105792) (#105815)
(cherry-picked from commit 006a453)
1 parent e422f35 commit c197bd8

File tree

1 file changed

+62
-33
lines changed

1 file changed

+62
-33
lines changed

Doc/library/typing.rst

+62-33
Original file line numberDiff line numberDiff line change
@@ -2265,16 +2265,19 @@ Functions and decorators
22652265

22662266
.. versionadded:: 3.11
22672267

2268-
.. decorator:: dataclass_transform
2268+
.. decorator:: dataclass_transform(*, eq_default=True, order_default=False, \
2269+
kw_only_default=False, \
2270+
field_specifiers=(), **kwargs)
22692271
22702272
Decorator to mark an object as providing
2271-
:func:`~dataclasses.dataclass`-like behavior.
2273+
:func:`dataclass <dataclasses.dataclass>`-like behavior.
22722274

22732275
``dataclass_transform`` may be used to
22742276
decorate a class, metaclass, or a function that is itself a decorator.
22752277
The presence of ``@dataclass_transform()`` tells a static type checker that the
22762278
decorated object performs runtime "magic" that
2277-
transforms a class in a similar way to :func:`dataclasses.dataclass`.
2279+
transforms a class in a similar way to
2280+
:func:`@dataclasses.dataclass <dataclasses.dataclass>`.
22782281

22792282
Example usage with a decorator function:
22802283

@@ -2330,38 +2333,64 @@ Functions and decorators
23302333
customize the default behaviors of the decorated class, metaclass, or
23312334
function:
23322335

2333-
* ``eq_default`` indicates whether the ``eq`` parameter is assumed to be
2334-
``True`` or ``False`` if it is omitted by the caller.
2335-
* ``order_default`` indicates whether the ``order`` parameter is
2336-
assumed to be True or False if it is omitted by the caller.
2337-
* ``kw_only_default`` indicates whether the ``kw_only`` parameter is
2338-
assumed to be True or False if it is omitted by the caller.
2339-
* ``field_specifiers`` specifies a static list of supported classes
2340-
or functions that describe fields, similar to ``dataclasses.field()``.
2341-
* Arbitrary other keyword arguments are accepted in order to allow for
2342-
possible future extensions.
2343-
2344-
Type checkers recognize the following optional arguments on field
2336+
:param bool eq_default:
2337+
Indicates whether the ``eq`` parameter is assumed to be
2338+
``True`` or ``False`` if it is omitted by the caller.
2339+
Defaults to ``True``.
2340+
2341+
:param bool order_default:
2342+
Indicates whether the ``order`` parameter is
2343+
assumed to be ``True`` or ``False`` if it is omitted by the caller.
2344+
Defaults to ``False``.
2345+
2346+
:param bool kw_only_default:
2347+
Indicates whether the ``kw_only`` parameter is
2348+
assumed to be ``True`` or ``False`` if it is omitted by the caller.
2349+
Defaults to ``False``.
2350+
2351+
:param field_specifiers:
2352+
Specifies a static list of supported classes
2353+
or functions that describe fields, similar to :func:`dataclasses.field`.
2354+
Defaults to ``()``.
2355+
:type field_specifiers: tuple[Callable[..., Any], ...]
2356+
2357+
:param Any \**kwargs:
2358+
Arbitrary other keyword arguments are accepted in order to allow for
2359+
possible future extensions.
2360+
2361+
Type checkers recognize the following optional parameters on field
23452362
specifiers:
23462363

2347-
* ``init`` indicates whether the field should be included in the
2348-
synthesized ``__init__`` method. If unspecified, ``init`` defaults to
2349-
``True``.
2350-
* ``default`` provides the default value for the field.
2351-
* ``default_factory`` provides a runtime callback that returns the
2352-
default value for the field. If neither ``default`` nor
2353-
``default_factory`` are specified, the field is assumed to have no
2354-
default value and must be provided a value when the class is
2355-
instantiated.
2356-
* ``factory`` is an alias for ``default_factory``.
2357-
* ``kw_only`` indicates whether the field should be marked as
2358-
keyword-only. If ``True``, the field will be keyword-only. If
2359-
``False``, it will not be keyword-only. If unspecified, the value of
2360-
the ``kw_only`` parameter on the object decorated with
2361-
``dataclass_transform`` will be used, or if that is unspecified, the
2362-
value of ``kw_only_default`` on ``dataclass_transform`` will be used.
2363-
* ``alias`` provides an alternative name for the field. This alternative
2364-
name is used in the synthesized ``__init__`` method.
2364+
.. list-table:: **Recognised parameters for field specifiers**
2365+
:header-rows: 1
2366+
:widths: 20 80
2367+
2368+
* - Parameter name
2369+
- Description
2370+
* - ``init``
2371+
- Indicates whether the field should be included in the
2372+
synthesized ``__init__`` method. If unspecified, ``init`` defaults to
2373+
``True``.
2374+
* - ``default``
2375+
- Provides the default value for the field.
2376+
* - ``default_factory``
2377+
- Provides a runtime callback that returns the
2378+
default value for the field. If neither ``default`` nor
2379+
``default_factory`` are specified, the field is assumed to have no
2380+
default value and must be provided a value when the class is
2381+
instantiated.
2382+
* - ``factory``
2383+
- An alias for the ``default_factory`` parameter on field specifiers.
2384+
* - ``kw_only``
2385+
- Indicates whether the field should be marked as
2386+
keyword-only. If ``True``, the field will be keyword-only. If
2387+
``False``, it will not be keyword-only. If unspecified, the value of
2388+
the ``kw_only`` parameter on the object decorated with
2389+
``dataclass_transform`` will be used, or if that is unspecified, the
2390+
value of ``kw_only_default`` on ``dataclass_transform`` will be used.
2391+
* - ``alias``
2392+
- Provides an alternative name for the field. This alternative
2393+
name is used in the synthesized ``__init__`` method.
23652394

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

0 commit comments

Comments
 (0)