New converter parameter

This specification introduces a new parameter named converter to the dataclasses.field() function. If provided, it represents a single-argument callable used to convert all values when assigning to the associated attribute.

For frozen dataclasses, the converter is only used inside a dataclass-synthesized __init__ when setting the attribute. For non-frozen dataclasses, the converter is used for all attribute assignment (E.g. obj.attr = value), which includes assignment of default values.

The converter is not used when reading attributes, as the attributes should already have been converted.

Adding this parameter also implies the following changes:

• A converter attribute will be added to dataclasses.Field.
• converter will be added to dataclass_transform()’s list of supported field specifier parameters.

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,).

Impact on typing

A converter must be a callable that accepts a single positional argument, and the parameter type corresponding to this positional argument provides the type of the the synthesized __init__ parameter associated with the field.

In other words, the argument provided for the converter parameter must be compatible with Callable[[T], X] where T is the input type for the converter and X is the output type of the converter.

Indirection of allowable argument types

One downside introduced by this PEP is that knowing what argument types are allowed in the dataclass’ __init__ and during attribute assignment is not immediately obvious from reading the dataclass. The allowable types are defined by the converter.

This is true when reading code from source, however typing-related aides such as typing.reveal_type and “IntelliSense” in an IDE should make it easy to know exactly what types are allowed without having to read any source code.

Just adding “converter” to typing.dataclass_transform’s field_specifiers

The idea of isolating this addition to dataclass_transform() was briefly discussed on Typing-SIG where it was suggested to broaden this to dataclasses more generally.

Additionally, adding this to dataclasses ensures anyone can reap the benefits without requiring additional libraries.

Not converting default values

There are pros and cons with both converting and not converting default values. Leaving default values as-is allows type-checkers and dataclass authors to expect that the type of the default matches the type of the field. However, converting default values has three large advantages:

1. Consistency. Unconditionally converting all values that are assigned to the attribute, involves fewer “special rules” that users must remember.
2. Simpler defaults. Allowing the default value to have the same type as user-provided values means dataclass authors get the same conveniences as their callers.
3. Compatibility with attrs. Attrs unconditionally uses the converter to convert default values.

Automatic conversion using the field’s type

One idea could be to allow the type of the field specified (e.g. str or int) to be used as a converter for each argument provided. Pydantic’s data conversion has semantics which appear to be similar to this approach.

This works well for fairly simple types, but leads to ambiguity in expected behavior for complex types such as generics. E.g. For tuple[int, ...] it is ambiguous if the converter is supposed to simply convert an iterable to a tuple, or if it is additionally supposed to convert each element type to int. Or for int | None, which isn’t callable.

Deducing the attribute type from the return type of the converter

Another idea would be to allow the user to omit the attribute’s type annotation if providing a field with a converter argument. Although this would reduce the common repetition this PEP introduces (e.g. x: str = field(converter=str)), it isn’t clear how to best support this while maintaining the current dataclass semantics (namely, that the attribute order is preserved for things like the synthesized __init__, or dataclasses.fields). This is because there isn’t an easy way in Python (today) to get the annotation-only attributes interspersed with un-annotated attributes in the order they were defined.

A sentinel annotation could be applied (e.g. x: FromConverter = ...), however this breaks a fundamental assumption of type annotations.

Lastly, this is feasible if all fields (including those without a converter) were assigned to dataclasses.field, which means the class’ own namespace holds the order, however this trades repetition of type+converter with repetition of field assignment. The end result is no gain or loss of repetition, but with the added complexity of dataclasses semantics.

This PEP doesn’t suggest it can’t or shouldn’t be done. Just that it isn’t included in this PEP.