PEP 681: Decorator placement, future params, unstated semantics (#2498)

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
 =========