@@ -2265,16 +2265,19 @@ Functions and decorators
2265
2265
2266
2266
.. versionadded :: 3.11
2267
2267
2268
- .. decorator :: dataclass_transform
2268
+ .. decorator :: dataclass_transform(*, eq_default=True, order_default=False, \
2269
+ kw_only_default=False, \
2270
+ field_specifiers=(), **kwargs)
2269
2271
2270
2272
Decorator to mark an object as providing
2271
- :func: `~ dataclasses.dataclass `-like behavior.
2273
+ :func: `dataclass < dataclasses.dataclass> `-like behavior.
2272
2274
2273
2275
``dataclass_transform `` may be used to
2274
2276
decorate a class, metaclass, or a function that is itself a decorator.
2275
2277
The presence of ``@dataclass_transform() `` tells a static type checker that the
2276
2278
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> `.
2278
2281
2279
2282
Example usage with a decorator function:
2280
2283
@@ -2330,38 +2333,64 @@ Functions and decorators
2330
2333
customize the default behaviors of the decorated class, metaclass, or
2331
2334
function:
2332
2335
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
2345
2362
specifiers:
2346
2363
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.
2365
2394
2366
2395
At runtime, this decorator records its arguments in the
2367
2396
``__dataclass_transform__ `` attribute on the decorated object.
0 commit comments