From b10f0f86e94dda560417c506b1825aefbf9ae209 Mon Sep 17 00:00:00 2001 From: Erik De Bonte Date: Tue, 5 Apr 2022 06:55:23 -0700 Subject: [PATCH] PEP 681: Rename `field descriptor` to `field specifier` (#2503) --- pep-0681.rst | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/pep-0681.rst b/pep-0681.rst index 6fad2ddca..1c004071f 100644 --- a/pep-0681.rst +++ b/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 - descriptors supported). The standard dataclass behavior supports - only one type of field descriptor called ``Field`` plus a helper + ``field_specifiers`` will default to an empty tuple (no field + specifiers supported). The standard dataclass behavior supports + 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 -these field descriptors. This specification formalizes the names and +specifier classes typically use common parameter names to construct +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.