PEP 681: Rename `field descriptor` to `field specifier` (#2503)

pep-0681.rst

@@ -35,7 +35,7 @@ These behaviors include:
   ``__le__``, ``__gt__`` and ``__ge__`` methods.
 * Supporting "frozen" classes, a way to enforce immutability during
   static type checking.
-* Supporting "field descriptors", which describe attributes of
+* Supporting "field specifiers", which describe attributes of
   individual fields that a static type checker must be aware of,
   such as whether a default value is provided for the field.
 
@@ -218,7 +218,7 @@ customization of default behaviors:
       eq_default: bool = True,
       order_default: bool = False,
       kw_only_default: bool = False,
-      field_descriptors: tuple[type | Callable[..., Any], ...] = (),
+      field_specifiers: tuple[type | Callable[..., Any], ...] = (),
   ) -> Callable[[_T], _T]: ...
 
 * ``eq_default`` indicates whether the ``eq`` parameter is assumed to
@@ -233,13 +233,13 @@ customization of default behaviors:
   assumed to be True or False if it is omitted by the caller. If not
   specified, ``kw_only_default`` will default to False (the default
   assumption for dataclass).
-* ``field_descriptors`` specifies a static list of supported classes
+* ``field_specifiers`` specifies a static list of supported classes
   that describe fields. Some libraries also supply functions to
-  allocate instances of field descriptors, and those functions may
+  allocate instances of field specifiers, and those functions may
   also be specified in this tuple. If not specified,
-  ``field_descriptors`` will default to an empty tuple (no field
+  ``field_specifiers`` will default to an empty tuple (no field
-  descriptors supported). The standard dataclass behavior supports
+  specifiers supported). The standard dataclass behavior supports
-  only one type of field descriptor called ``Field`` plus a helper
+  only one type of field specifier called ``Field`` plus a helper
   function (``field``) that instantiates this class, so if we were
   describing the stdlib dataclass behavior, we would provide the
   tuple argument ``(dataclasses.Field, dataclasses.field)``.
@@ -344,26 +344,26 @@ Metaclass example
       name: str
 
 
-Field descriptors
+Field specifiers
 -----------------
 
 Most libraries that support dataclass-like semantics provide one or
-more "field descriptor" types that allow a class definition to provide
+more "field specifier" types that allow a class definition to provide
 additional metadata about each field in the class. This metadata can
 describe, for example, default values, or indicate whether the field
 should be included in the synthesized ``__init__`` method.
 
-Field descriptors can be omitted in cases where additional metadata is
+Field specifiers can be omitted in cases where additional metadata is
 not required:
 
 .. code-block:: python
 
   @dataclass
   class Employee:
-      # Field with no descriptor
+      # Field with no specifier
       name: str
   
-      # Field that uses field descriptor class instance
+      # Field that uses field specifier class instance
       age: Optional[int] = field(default=None, init=False)
   
       # Field with type annotation and simple initializer to
@@ -375,12 +375,12 @@ not required:
       office_number = "unassigned"
 
 
-Field descriptor parameters
+Field specifier parameters
 '''''''''''''''''''''''''''
 
 Libraries that support dataclass-like semantics and support field
-descriptor classes typically use common parameter names to construct
+specifier classes typically use common parameter names to construct
-these field descriptors. This specification formalizes the names and
+these field specifiers. 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.
 
@@ -388,13 +388,13 @@ 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
+Field specifier classes are allowed to use other
 parameters in their constructors, and those parameters can be
 positional and may use other names.
 
 * ``init`` is an optional bool parameter that indicates whether the
   field should be included in the synthesized ``__init__`` method. If
-  unspecified, ``init`` defaults to True. Field descriptor functions
+  unspecified, ``init`` defaults to True. Field specifier functions
   can use overloads that implicitly specify the value of ``init``
   using a literal bool value type
   (``Literal[False]`` or ``Literal[True]``).
@@ -446,7 +446,7 @@ This example demonstrates the above:
   
   @typing.dataclass_transform(
       kw_only_default=True,
-      field_descriptors=(model_field, ))
+      field_specifiers=(model_field, ))
   def create_model(
       *,
       init: bool = True,
@@ -476,7 +476,7 @@ For example:
     "eq_default": True,
     "order_default": False,
     "kw_only_default": False,
-    "field_descriptors": (),
+    "field_specifiers": (),
   }
 
 
@@ -700,10 +700,10 @@ 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
+``converter`` field specifier parameter
 ----------------------------------------
 
-The attrs library supports a ``converter`` field descriptor parameter,
+The attrs library supports a ``converter`` field specifier parameter,
 which is a ``Callable`` that is called by the generated
 ``__init__`` method to convert the supplied value to some other
 desired value. This is tricky to support since the parameter type in
@@ -716,7 +716,7 @@ Some aspects of this issue are detailed in a
 
 There may be no good way to support this because there's not enough
 information to derive the type of the input parameter. One possible
-solution would be to add support for a ``converter`` field descriptor
+solution would be to add support for a ``converter`` field specifier
 parameter but then use the ``Any`` type for the corresponding
 parameter in the ``__init__`` method.