diff --git a/pep-0681.rst b/pep-0681.rst index 1d3dc0a32..6fad2ddca 100644 --- a/pep-0681.rst +++ b/pep-0681.rst @@ -78,6 +78,7 @@ sync will make it easier for dataclass users to understand and use ``dataclass_transform`` and will simplify the maintenance of dataclass support in type checkers. + Specification ============= @@ -94,6 +95,10 @@ a class, endowing it with dataclass-like behaviors. If ``dataclass_transform`` is applied to a function, using the decorated function as a decorator is assumed to apply dataclass-like semantics. +If the function has overloads, the ``dataclass_transform`` decorator can +be applied to the implementation of the function or any one, but not more +than one, of the overloads. + If ``dataclass_transform`` is applied to a class, dataclass-like semantics will be assumed for any class that derives from the decorated class or uses the decorated class as a metaclass. @@ -239,6 +244,11 @@ customization of default behaviors: describing the stdlib dataclass behavior, we would provide the tuple argument ``(dataclasses.Field, dataclasses.field)``. +In the future, we may add additional parameters to +``dataclass_transform`` as needed to support common behaviors in user +code. These additions will be made after reaching consensus on +typing-sig rather than via additional PEPs. + The following sections provide additional examples showing how these parameters are used. @@ -473,8 +483,13 @@ For example: Dataclass semantics ------------------- -The following dataclass semantics are implied when a function or class -decorated with ``dataclass_transform`` is in use. +Except where stated otherwise in this PEP, classes impacted by +``dataclass_transform``, either by inheriting from a class that is +decorated with ``dataclass_transform`` or by being decorated with +a function decorated with ``dataclass_transform``, are assumed to +behave like stdlib ``dataclass``. + +This includes, but is not limited to, the following semantics: * Frozen dataclasses cannot inherit from non-frozen dataclasses. A class that has been decorated with ``dataclass_transform`` is @@ -553,8 +568,9 @@ Undefined behavior ------------------ If multiple ``dataclass_transform`` decorators are found, either on a -single function/class or within a class hierarchy, the resulting -behavior is undefined. Library authors should avoid these scenarios. +single function (including its overloads), a single class, or within a +class hierarchy, the resulting behavior is undefined. Library authors +should avoid these scenarios. Reference Implementation @@ -684,7 +700,6 @@ support descriptor-typed fields. In fact it does, but type checkers led to our misunderstanding. For more details, see the `Pyright bug <#pyright-descriptor-bug_>`__. - ``converter`` field descriptor parameter ---------------------------------------- @@ -724,6 +739,7 @@ References .. _#class-var: https://docs.python.org/3/library/dataclasses.html#class-variables .. _#pyright-descriptor-bug: https://github.com/microsoft/pyright/issues/3245 + Copyright =========