Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PEP 681: Rename "field descriptor" to "field specifier" #2503

Merged
merged 1 commit into from
Apr 5, 2022
Merged

PEP 681: Rename "field descriptor" to "field specifier" #2503

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 22 additions & 22 deletions pep-0681.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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)``.
Expand Down Expand Up @@ -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
Expand All @@ -375,26 +375,26 @@ 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.

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]``).
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -476,7 +476,7 @@ For example:
"eq_default": True,
"order_default": False,
"kw_only_default": False,
"field_descriptors": (),
"field_specifiers": (),
}


Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand Down