Rejection Notice

The reasons for the 2024 Steering Council rejection include:

• We did not find evidence of a strong consensus that this feature was needed in the standard library, despite some proponents arguing in favor in order to reduce their dependence on third party packages. For those who need such functionality, we think those existing third party libraries such as attrs and Pydantic (which the PEP references) are acceptable alternatives.
• This feature seems to us like an accumulation of what could be considered more cruft in the standard library, leading us ever farther away from the “simple” use cases that dataclasses are ideal for.
• Reading the “How to Teach This” section of the PEP gives us pause that the pitfalls and gotchas are significant, with a heightened confusion and complexity outweighing any potential benefits.
• The PEP seems more focused toward helping type checkers than people using the library.

Abstract

PEP 557 added dataclasses to the Python stdlib. PEP 681 added dataclass_transform() to help type checkers understand several common dataclass-like libraries, such as attrs, Pydantic, and object relational mapper (ORM) packages such as SQLAlchemy and Django.

A common feature other libraries provide over the standard library implementation is the ability for the library to convert arguments given at initialization time into the types expected for each field using a user-provided conversion function.

Therefore, this PEP adds a converter parameter to dataclasses.field() (along with the requisite changes to dataclasses.Field and dataclass_transform()) to specify the function to use to convert the input value for each field to the representation to be stored in the dataclass.

Motivation

There is no existing, standard way for dataclasses or third-party dataclass-like libraries to support argument conversion in a type-checkable way. To work around this limitation, library authors/users are forced to choose to:

• Opt-in to a custom Mypy plugin. These plugins help Mypy understand the conversion semantics, but not other tools.
• Shift conversion responsibility onto the caller of the dataclass constructor. This can make constructing certain dataclasses unnecessarily verbose and repetitive.
• Provide a custom __init__ which declares “wider” parameter types and converts them when setting the appropriate attribute. This not only duplicates the typing annotations between the converter and __init__, but also opts the user out of many of the features dataclasses provides.
• Provide a custom __init__ but without meaningful type annotations for the parameter types requiring conversion.

None of these choices are ideal.

Rationale

Adding argument conversion semantics is useful and beneficial enough that most dataclass-like libraries provide support. Adding this feature to the standard library means more users are able to opt-in to these benefits without requiring third-party libraries. Additionally third-party libraries are able to clue type-checkers into their own conversion semantics through added support in dataclass_transform(), meaning users of those libraries benefit as well.

Specification

def str_or_none(x: Any) -> str | None:
  return str(x) if x is not None else None

@dataclasses.dataclass
class InventoryItem:
    # `converter` as a type (including a GenericAlias).
    id: int = dataclasses.field(converter=int)
    skus: tuple[int, ...] = dataclasses.field(converter=tuple[int, ...])
    # `converter` as a callable.
    vendor: str | None = dataclasses.field(converter=str_or_none))
    names: tuple[str, ...] = dataclasses.field(
      converter=lambda names: tuple(map(str.lower, names))
    )  # Note that lambdas are supported, but discouraged as they are untyped.

    # The default value is also converted; therefore the following is not a
    # type error.
    stock_image_path: pathlib.PurePosixPath = dataclasses.field(
      converter=pathlib.PurePosixPath, default="assets/unknown.png"
    )

    # Default value conversion extends to `default_factory`;
    # therefore the following is also not a type error.
    shelves: tuple = dataclasses.field(
      converter=tuple, default_factory=list
    )

item1 = InventoryItem(
  "1",
  [234, 765],
  None,
  ["PYTHON PLUSHIE", "FLUFFY SNAKE"]
)
# item1's repr would be (with added newlines for readability):
#   InventoryItem(
#     id=1,
#     skus=(234, 765),
#     vendor=None,
#     names=('PYTHON PLUSHIE', 'FLUFFY SNAKE'),
#     stock_image_path=PurePosixPath('assets/unknown.png'),
#     shelves=()
#   )

# Attribute assignment also participates in conversion.
item1.skus = [555]
# item1's skus attribute is now (555,).

Backward Compatibility

These changes don’t introduce any compatibility problems since they only introduce opt-in new features.

Security Implications

There are no direct security concerns with these changes.

How to Teach This

Documentation and examples explaining the new parameter and behavior will be added to the relevant sections of the docs site (primarily on dataclasses) and linked from the What’s New document.

The added documentation/examples will also cover the “common pitfalls” that users of converters are likely to encounter. Such pitfalls include:

• Needing to handle None/sentinel values.
• Needing to handle values that are already of the correct type.
• Avoiding lambdas for converters, as the synthesized __init__ parameter’s type will become Any.
• Forgetting to convert values in the bodies of user-defined __init__ in frozen dataclasses.
• Forgetting to convert values in the bodies of user-defined __setattr__ in non-frozen dataclasses.

Additionally, potentially confusing pattern matching semantics should be covered:

@dataclass
class Point:
    x: int = field(converter=int)
    y: int

match Point(x="0", y=0):
    case Point(x="0", y=0):  # Won't be matched
        ...
    case Point():  # Will be matched
        ...
    case _:
        ...

However it’s worth noting this behavior is true of any type that does conversion in its initializer, and type-checkers should be able to catch this pitfall:

match int("0"):
  case int("0"):  # Won't be matched
      ...
  case _:  # Will be matched
      ...

Reference Implementation

The attrs library already includes a converter parameter exhibiting the same converter semantics (converting in the initializer and on attribute setting) when using the @define class decorator.

CPython support is implemented on a branch in the author’s fork.

Rejected Ideas

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.