Skip to content

Commit

Permalink
Add PEP 712 converters to the dataclasses spec (#1783)
Browse files Browse the repository at this point in the history
* Add PEP 712 converters

* [pre-commit.ci] auto fixes from pre-commit.com hooks

* Apply suggestions from code review

Thanks Carl!

Co-authored-by: Carl Meyer <[email protected]>

* Apply suggestions from code review

Co-authored-by: Eric Traut <[email protected]>

* Update dataclasses.rst

* [pre-commit.ci] auto fixes from pre-commit.com hooks

* Update dataclasses.rst

* [pre-commit.ci] auto fixes from pre-commit.com hooks

* Update dataclasses.rst

* [pre-commit.ci] auto fixes from pre-commit.com hooks

* Update dataclasses.rst

* Update dataclasses.rst

* Update docs/spec/dataclasses.rst

* Comments

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Carl Meyer <[email protected]>
Co-authored-by: Eric Traut <[email protected]>
  • Loading branch information
4 people authored Jul 20, 2024
1 parent ab074f6 commit dc1698d
Showing 1 changed file with 48 additions and 0 deletions.
48 changes: 48 additions & 0 deletions docs/spec/dataclasses.rst
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,8 @@ positional and may use other names.
* ``alias`` is an optional str parameter that provides an alternative
name for the field. This alternative name is used in the synthesized
``__init__`` method.
* ``converter`` is an optional parameter that specifies a
callable used to convert values when assigning to the field.

It is an error to specify more than one of ``default``,
``default_factory`` and ``factory``.
Expand Down Expand Up @@ -526,6 +528,52 @@ This includes, but is not limited to, the following semantics:
dataclass must be explicitly annotated as e.g. ``x: ClassVar[Final[int]] =
3``.

Converters
^^^^^^^^^^

The ``converter`` parameter can be specified in a field definition to provide a callable
used to convert values when assigning to the associated attribute. This feature allows for automatic type
conversion and validation during attribute assignment.

Converter behavior:

* The converter is used for all attribute assignment, including assignment
of default values, assignment in synthesized ``__init__`` methods
and direct attribute setting (e.g., ``obj.attr = value``).
* The converter is not used when reading attributes, as the attributes should already have been converted.

Typing rules for converters:

* The ``converter`` must be a callable that must accept a single positional argument
(but may accept other optional arguments, which are ignored for typing purposes).
* The type of the first positional parameter provides the type of the synthesized ``__init__`` parameter
for the field.
* The return type of the callable must be assignable to the field's declared type.
* If ``default`` or ``default_factory`` are provided, the type of the default value should be
assignable to the first positional parameter of the ``converter``.

Example usage:

.. code-block:: python
def str_or_none(x: Any) -> str | None:
return str(x) if x is not None else None
@custom_dataclass
class Example:
int_field: int = custom_field(converter=int)
str_field: str | None = custom_field(converter=str_or_none)
path_field: pathlib.Path = custom_field(
converter=pathlib.Path,
default="default/path.txt"
)
# Usage
example = Example("123", None, "some/path")
# example.int_field == 123
# example.str_field == None
# example.path_field == pathlib.Path("some/path")
Undefined behavior
^^^^^^^^^^^^^^^^^^
Expand Down

0 comments on commit dc1698d

Please sign in to comment.