PEP 681: kw_only field descriptor parameter is supported (#2381)

* kw_only field descriptor parameter is supported

* Sync features with dataclass

Author: debonte

pep-0681.rst

@@ -64,6 +64,12 @@ certain features or make small adjustments to the way they use them.
 That's already true for the Mypy custom plugins, which
 don't support every feature of every dataclass-like library.
 
+As new features are added to dataclass in the future, we intend, when
+appropriate, to add support for those features on
+``dataclass_transform`` as well. Keeping these two feature sets in
+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
 =============
@@ -185,8 +191,8 @@ the bool value (``True`` or ``False``) to be statically evaluated.
 * ``eq``.  ``order``, ``frozen``, ``init`` and ``unsafe_hash`` are parameters
   supported in the stdlib dataclass, with meanings defined in :pep:`557 <557#id7>`.
 * ``hash`` is an alias for the ``unsafe_hash`` parameter.
-* ``kw_only`` and ``slots`` are parameters supported in the stdlib dataclass,
-  first introduced in Python 3.10.
+* ``kw_only``, ``match_args`` and ``slots`` are parameters supported
+  in the stdlib dataclass, first introduced in Python 3.10.
 
 ``dataclass_transform`` parameters
 ----------------------------------
@@ -366,6 +372,11 @@ descriptor classes typically use common parameter names to construct
 these field descriptors. This specification formalizes the names and
 meanings of the parameters that must be understood for static type
 checkers. These standardized parameters must be keyword-only.
+
+These parameters are a superset of those supported by
+``dataclasses.field``, excluding those that do not have an impact on
+type checking such as ``compare`` and ``hash``.
+
 Field descriptor classes are allowed to use other
 parameters in their constructors, and those parameters can be
 positional and may use other names.
@@ -386,6 +397,12 @@ positional and may use other names.
 * ``factory`` is an alias for ``default_factory``. Stdlib dataclasses
   use the name ``default_factory``, but attrs uses the name ``factory``
   in many scenarios, so this alias is necessary for supporting attrs.
+* ``kw_only`` is an optional bool parameter that indicates whether the
+  field should be marked as keyword-only. If true, the field will be
+  keyword-only. If false, it will not be keyword-only. If unspecified,
+  the value of the ``kw_only`` parameter on the object decorated with
+  ``dataclass_transform`` will be used, or if that is unspecified, the
+  value of ``kw_only_default`` on ``dataclass_transform`` will be used.
 * ``alias`` is an optional str parameter that provides an alternative
   name for the field. This alternative name is used in the synthesized
   ``__init__`` method.
@@ -612,13 +629,6 @@ a ``cmp`` parameter, since it only applies to attrs. Attrs users
 should use the dataclass-standard ``eq`` and ``order`` parameter names
 instead.
 
-``kw_only`` field descriptor parameter
---------------------------------------
-
-The attrs library supports a ``kw_only`` parameter for individual
-fields. We chose not to support a ``kw_only`` parameter, since it is
-specific to attrs.
-
 Automatic field name aliasing
 -----------------------------
 
@@ -629,7 +639,6 @@ underscore from the name of the corresponding ``__init__`` parameter.
 This proposal omits that behavior since it is specific to attrs. Users
 can manually alias these fields using the ``alias`` parameter.
 
-
 Alternate field ordering algorithms
 -----------------------------------