PEP 681 – Data Class Transforms | peps.python.org
PEP 681 – Data Class Transforms PEP 681 – Data Class Transforms Author : Erik De Bonte <erikd at microsoft.com>, Eric Traut <erictr at microsoft.com> Sponsor : Jelle Zijlstra <jelle.zijlstra at gmail.com> Discussions-To : Typing-SIG thread Status : Final Type : Standards Track Topic : Typing Created : 02-Dec-2021 Python-Version : 3.11 Post-History : 24-Apr-2021 , 13-Dec-2021 , 22-Feb-2022 Resolution : Python-Dev message Table of Contents Abstract Motivation Rationale Specification The dataclass_transform decorator Decorator function example Class example Metaclass example Decorator function and class/metaclass parameters dataclass_transform parameters Decorator function example Class example Metaclass example Field specifiers Field specifier parameters Runtime behavior Dataclass semantics Undefined behavior Reference Implementation Rejected Ideas auto_attribs parameter cmp parameter Automatic field name aliasing Alternate field ordering algorithms Fields redeclared in subclasses Django primary and foreign keys Class-wide default values Descriptor-typed field support converter field specifier parameter Copyright Important This PEP is a historical document: see The dataclass_transform decorator and @typing.dataclass_transform for up-to-date specs and documentation.
Canonical typing specs are maintained at the typing specs site ; runtime typing behaviour is described in the CPython documentation. × See the typing specification update process for how to propose changes to the typing spec. Abstract PEP 557 introduced the dataclass to the Python stdlib. Several popular libraries have behaviors that are similar to dataclasses, but these behaviors cannot be described using standard type annotations.
Such projects include attrs, pydantic, and object relational mapper (ORM) packages such as SQLAlchemy and Django. Most type checkers, linters and language servers have full support for dataclasses. This proposal aims to generalize this functionality and provide a way for third-party libraries to indicate that certain decorator functions, classes, and metaclasses provide behaviors similar to dataclasses. These behaviors include: Synthesizing an __init__ method based on declared data fields.
Optionally synthesizing __eq__ , __ne__ , __lt__ , __le__ , __gt__ and __ge__ methods. Supporting “frozen” classes, a way to enforce immutability during static type checking. 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. The full behavior of the stdlib dataclass is described in the Python documentation .
This proposal does not affect CPython directly except for the addition of a dataclass_transform decorator in typing.py . Motivation There is no existing, standard way for libraries with dataclass-like semantics to declare their behavior to type checkers. To work around this limitation, Mypy custom plugins have been developed for many of these libraries, but these plugins don’t work with other type checkers, linters or language servers.
They are also costly to maintain for library authors, and they require that Python developers know about the existence of these plugins and download and configure them within their environment. Rationale The intent of this proposal is not to support every feature of every library with dataclass-like semantics, but rather to make it possible to use the most common features of these libraries in a way that is compatible with static type checking.
If a user values these libraries and also values static type checking, they may need to avoid using certain features or make small adjustments to the way they use them. That’s already true for the Mypy custom plugins, which don’t support every feature of every dataclass-like library. As new features are added to dataclasses in the future, we intend, when appropriate, to add support for those features on dataclass_transform as well.
Keeping these two feature sets in sync will make it easier for dataclass users to understand and use dataclass_transform and will simplify the maintenance of dataclass support in type checkers. Additionally, we will consider adding dataclass_transform support in the future for features that have been adopted by multiple third-party libraries but are not supported by dataclasses. Specification The dataclass_transform decorator This specification introduces a new decorator function in the typing module named dataclass_transform .
This decorator can be applied to either a function that is itself a decorator, a class, or a metaclass. The presence of dataclass_transform tells a static type checker that the decorated function, class, or metaclass performs runtime “magic” that transforms a class, endowing it with dataclass-like behaviors. If dataclass_transform is applied to a function, using the decorated function as a decorator is assumed to apply dataclass-like semantics.
If the function has overloads, the dataclass_transform decorator can be applied to the implementation of the function or any one, but not more than one, of the overloads. When applied to an overload, the dataclass_transform decorator still impacts all usage of the function. If dataclass_transform is applied to a class, dataclass-like semantics will be assumed for any class that directly or indirectly derives from the decorated class or uses the decorated class as a metaclass.
Attributes on the decorated class and its base classes are not considered to be fields. Examples of each approach are shown in the following sections. Each example creates a CustomerModel class with dataclass-like semantics. The implementation of the decorated objects is omitted for brevity, but we assume that they modify classes in the following ways: They synthesize an __init__ method using data fields declared within the class and its parent classes.
They synthesize __eq__ and __ne__ methods. Type checkers supporting this PEP will recognize that the CustomerModel class can be instantiated using the synthesized __init__ method: # Using positional arguments c1 = CustomerModel ( 327 , "John Smith" ) # Using keyword arguments c2 = CustomerModel ( id = 327 , name = "John Smith" ) # These calls will generate runtime errors and should be flagged as # errors by a static type checker. c3 = CustomerModel () c4 = CustomerModel ( 327 , first_name = "John" ) c5 = CustomerModel ( 327 , "John Smith" , 0 ) Decorator function example _T = TypeVar ( "_T" ) # The ``create_model`` decorator is defined by a library. # This could be in a type stub or inline. @typing . dataclass_transform () def create_model ( cls : Type [ _T ]) -> Type [ _T ]: cls . __init__ = ... cls . __eq__ = ... cls . __ne__ = ... return cls # The ``create_model`` decorator can now be used to create new model # classes, like this: @create_model class CustomerModel : id : int name : str Class example # The ``ModelBase`` class is defined by a library.
This could be in # a type stub or inline. @typing . dataclass_transform () class ModelBase : ... # The ``ModelBase`` class can now be used to create new model # subclasses, like this: class CustomerModel ( ModelBase ): id : int name : str Metaclass example # The ``ModelMeta`` metaclass and ``ModelBase`` class are defined by # a library. This could be in a type stub or inline. @typing . dataclass_transform () class ModelMeta ( type ): ... class ModelBase ( metaclass = ModelMeta ): ... # The ``ModelBase`` class can now be used to create new model # subclasses, like this: class CustomerModel ( ModelBase ): id : int name : str Decorator function and class/metaclass parameters A decorator function, class, or metaclass that provides dataclass-like functionality may accept parameters that modify certain behaviors.
This specification defines the following parameters that static type checkers must honor if they are used by a dataclass transform. Each of these parameters accepts a bool argument, an
The rest of this page is on the live site.