Text of peps.python.org › pep-0557 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 557 – Data Classes | peps.python.org

PEP 557 – Data Classes PEP 557 – Data Classes Author : Eric V. Smith <eric at trueblade.com> Status : Final Type : Standards Track Created : 02-Jun-2017 Python-Version : 3.7 Post-History : 08-Sep-2017, 25-Nov-2017, 30-Nov-2017, 01-Dec-2017, 02-Dec-2017, 06-Jan-2018, 04-Mar-2018 Resolution : Python-Dev message Table of Contents Notice for Reviewers Abstract Rationale Specification Field objects post-init processing Class variables Init-only variables Frozen instances Inheritance Default factory functions Mutable default values Module level helper functions Discussion python-ideas discussion Support for automatically setting __slots__ ?

Why not just use namedtuple? Why not just use typing.NamedTuple? Why not just use attrs? post-init parameters asdict and astuple function names Rejected ideas Copying init=False fields after new object creation in replace() Automatically support mutable default values Examples Custom __init__ method A complicated example Acknowledgements References Copyright Notice for Reviewers This PEP and the initial implementation were drafted in a separate repo: https://github.com/ericvsmith/dataclasses .

Before commenting in a public forum please at least read the discussion listed at the end of this PEP. Abstract This PEP describes an addition to the standard library called Data Classes. Although they use a very different mechanism, Data Classes can be thought of as “mutable namedtuples with defaults”. Because Data Classes use normal class definition syntax, you are free to use inheritance, metaclasses, docstrings, user-defined methods, class factories, and other Python class features.

A class decorator is provided which inspects a class definition for variables with type annotations as defined in PEP 526 , “Syntax for Variable Annotations”. In this document, such variables are called fields. Using these fields, the decorator adds generated method definitions to the class to support instance initialization, a repr, comparison methods, and optionally other methods as described in the Specification section.

Such a class is called a Data Class, but there’s really nothing special about the class: the decorator adds generated methods to the class and returns the same class it was given. As an example: @dataclass class InventoryItem : '''Class for keeping track of an item in inventory.''' name : str unit_price : float quantity_on_hand : int = 0 def total_cost ( self ) -> float : return self . unit_price * self . quantity_on_hand The @dataclass decorator will add the equivalent of these methods to the InventoryItem class: def __init__ ( self , name : str , unit_price : float , quantity_on_hand : int = 0 ) -> None : self . name = name self . unit_price = unit_price self . quantity_on_hand = quantity_on_hand def __repr__ ( self ): return f 'InventoryItem(name= { self . name !r} , unit_price= { self . unit_price !r} , quantity_on_hand= { self . quantity_on_hand !r} )' def __eq__ ( self , other ): if other . __class__ is self . __class__ : return ( self . name , self . unit_price , self . quantity_on_hand ) == ( other . name , other . unit_price , other . quantity_on_hand ) return NotImplemented def __ne__ ( self , other ): if other . __class__ is self . __class__ : return ( self . name , self . unit_price , self . quantity_on_hand ) != ( other . name , other . unit_price , other . quantity_on_hand ) return NotImplemented def __lt__ ( self , other ): if other . __class__ is self . __class__ : return ( self . name , self . unit_price , self . quantity_on_hand ) < ( other . name , other . unit_price , other . quantity_on_hand ) return NotImplemented def __le__ ( self , other ): if other . __class__ is self . __class__ : return ( self . name , self . unit_price , self . quantity_on_hand ) <= ( other . name , other . unit_price , other . quantity_on_hand ) return NotImplemented def __gt__ ( self , other ): if other . __class__ is self . __class__ : return ( self . name , self . unit_price , self . quantity_on_hand ) > ( other . name , other . unit_price , other . quantity_on_hand ) return NotImplemented def __ge__ ( self , other ): if other . __class__ is self . __class__ : return ( self . name , self . unit_price , self . quantity_on_hand ) >= ( other . name , other . unit_price , other . quantity_on_hand ) return NotImplemented Data Classes save you from writing and maintaining these methods.

Rationale There have been numerous attempts to define classes which exist primarily to store values which are accessible by attribute lookup. Some examples include: collections.namedtuple in the standard library. typing.NamedTuple in the standard library. The popular attrs [1] project. George Sakkis’ recordType recipe [2] , a mutable data type inspired by collections.namedtuple. Many example online recipes [3] , packages [4] , and questions [5] .

David Beazley used a form of data classes as the motivating example in a PyCon 2013 metaclass talk [6] . So, why is this PEP needed? With the addition of PEP 526 , Python has a concise way to specify the type of class members. This PEP leverages that syntax to provide a simple, unobtrusive way to describe Data Classes. With two exceptions, the specified attribute type annotation is completely ignored by Data Classes. No base classes or metaclasses are used by Data Classes.

Users of these classes are free to use inheritance and metaclasses without any interference from Data Classes. The decorated classes are truly “normal” Python classes. The Data Class decorator should not interfere with any usage of the class. One main design goal of Data Classes is to support static type checkers. The use of PEP 526 syntax is one example of this, but so is the design of the fields() function and the @dataclass decorator.

Due to their very dynamic nature, some of the libraries mentioned above are difficult to use with static type checkers. Data Classes are not, and are not intended to be, a replacement mechanism for all of the above libraries. But being in the standard library will allow many of the simpler use cases to instead leverage Data Classes. Many of the libraries listed have different feature sets, and will of course continue to exist and prosper.

Where is it not appropriate to use Data Classes? API compatibility with tuples or dicts is required. Type validation beyond that provided by PEPs 484 and 526 is required, or value validation or conversion is required. Specification All of the functions described in this PEP will live in a module named dataclasses . A function dataclass which is typically used as a class decorator is provided to post-process classes and add generated methods, described below.

The dataclass decorator examines the class to find field s. A field is defined as any variable identified in __annotations__ . That is, a variable that has a type annotation. With two exceptions described below, none of the Data Class machinery examines the type specified in the annotation. Note that __annotations__ is guaranteed to be an ordered mapping, in class declaration order. The order of the fields in all of the generated methods is the order in which they appear in the class.

The dataclass decorator will add various “dunder” methods to the class, described below. If any of the added methods already exist on the class, a TypeError will be raised. The decorator returns the same class that is called on: no new class is created. The dataclass decorator is typically used with no parameters and no parentheses. However, it also supports the following logical signature: def dataclass ( * , init = True , repr = True , eq = True , order = False , unsafe_hash = False , frozen = False ) If dataclass is used just as a simple decorator with no parameters, it acts as if it has the default values documented in this signature.

That is, these three uses of @dataclass are equivalent: @dataclass class C : ... @dataclass () class C : ... @dataclass ( init = True , repr = True , eq = True , order = False , un

The rest of this page is on the live site.