Field objects

Field objects describe each defined field. These objects arecreated internally, and are returned by thefields() module-levelmethod (see below). Users should never instantiate aFieldobject directly. Its documented attributes are:

• name: The name of the field.
• type: The type of the field.
• default,default_factory,init,repr,hash,compare, andmetadata have the identical meaning and valuesas they do in thefield() declaration.

Other attributes may exist, but they are private and must not beinspected or relied on.

post-init processing

The generated__init__ code will call a method named__post_init__, if it is defined on the class. It will be calledasself.__post_init__(). If no__init__ method is generated,then__post_init__ will not automatically be called.

Among other uses, this allows for initializing field values thatdepend on one or more other fields. For example:

@dataclassclassC:a:floatb:floatc:float=field(init=False)def__post_init__(self):self.c=self.a+self.b

See the section below on init-only variables for ways to passparameters to__post_init__(). Also see the warning about howreplace() handlesinit=False fields.

Class variables

One place wheredataclass actually inspects the type of a field isto determine if a field is a class variable as defined inPEP 526. Itdoes this by checking if the type of the field istyping.ClassVar.If a field is aClassVar, it is excluded from consideration as afield and is ignored by the Data Class mechanisms. For morediscussion, see[8]. SuchClassVar pseudo-fields are notreturned by the module-levelfields() function.

Init-only variables

The other place wheredataclass inspects a type annotation is todetermine if a field is an init-only variable. It does this by seeingif the type of a field is of typedataclasses.InitVar. If a fieldis anInitVar, it is considered a pseudo-field called an init-onlyfield. As it is not a true field, it is not returned by themodule-levelfields() function. Init-only fields are added asparameters to the generated__init__ method, and are passed tothe optional__post_init__ method. They are not otherwise usedby Data Classes.

For example, suppose a field will be initialized from a database, if avalue is not provided when creating the class:

@dataclassclassC:i:intj:int=Nonedatabase:InitVar[DatabaseType]=Nonedef__post_init__(self,database):ifself.jisNoneanddatabaseisnotNone:self.j=database.lookup('j')c=C(10,database=my_database)

In this case,fields() will returnField objects fori andj, but not fordatabase.

Frozen instances

It is not possible to create truly immutable Python objects. However,by passingfrozen=True to the@dataclass decorator you canemulate immutability. In that case, Data Classes will add__setattr__ and__delattr__ methods to the class. Thesemethods will raise aFrozenInstanceError when invoked.

There is a tiny performance penalty when usingfrozen=True:__init__ cannot use simple assignment to initialize fields, andmust useobject.__setattr__.

Inheritance

When the Data Class is being created by the@dataclass decorator,it looks through all of the class’s base classes in reverse MRO (thatis, starting atobject) and, for each Data Class that it finds,adds the fields from that base class to an ordered mapping of fields.After all of the base class fields are added, it adds its own fieldsto the ordered mapping. All of the generated methods will use thiscombined, calculated ordered mapping of fields. Because the fieldsare in insertion order, derived classes override base classes. Anexample:

@dataclassclassBase:x:Any=15.0y:int=0@dataclassclassC(Base):z:int=10x:int=15

The final list of fields is, in order,x,y,z. The finaltype ofx isint, as specified in classC.

The generated__init__ method forC will look like:

def__init__(self,x:int=15,y:int=0,z:int=10):

Default factory functions

If a field specifies adefault_factory, it is called with zeroarguments when a default value for the field is needed. For example,to create a new instance of a list, use:

l:list=field(default_factory=list)

If a field is excluded from__init__ (usinginit=False) andthe field also specifiesdefault_factory, then the default factoryfunction will always be called from the generated__init__function. This happens because there is no other way to give thefield an initial value.

Mutable default values

Python stores default member variable values in class attributes.Consider this example, not using Data Classes:

classC:x=[]defadd(self,element):self.x+=elemento1=C()o2=C()o1.add(1)o2.add(2)asserto1.x==[1,2]asserto1.xiso2.x

Note that the two instances of classC share the same classvariablex, as expected.

Using Data Classes,if this code was valid:

@dataclassclassD:x:List=[]defadd(self,element):self.x+=element

it would generate code similar to:

classD:x=[]def__init__(self,x=x):self.x=xdefadd(self,element):self.x+=elementassertD().xisD().x

This has the same issue as the original example using classC.That is, two instances of classD that do not specify a value forx when creating a class instance will share the same copy ofx. Because Data Classes just use normal Python class creationthey also share this problem. There is no general way for DataClasses to detect this condition. Instead, Data Classes will raise aTypeError if it detects a default parameter of typelist,dict, orset. This is a partial solution, but it does protectagainst many common errors. SeeAutomatically support mutabledefault values in the Rejected Ideas section for more details.

Using default factory functions is a way to create new instances ofmutable types as default values for fields:

@dataclassclassD:x:list=field(default_factory=list)assertD().xisnotD().x

Module level helper functions

• fields(class_or_instance): Returns a tuple ofField objectsthat define the fields for this Data Class. Accepts either a DataClass, or an instance of a Data Class. RaisesValueError if notpassed a Data Class or instance of one. Does not returnpseudo-fields which areClassVar orInitVar.
• asdict(instance,*,dict_factory=dict): Converts the Data Classinstance to a dict (by using the factory functiondict_factory). Each Data Class is converted to a dict of itsfields, as name:value pairs. Data Classes, dicts, lists, and tuplesare recursed into. For example:

  @dataclassclassPoint:x:inty:int@dataclassclassC:l:List[Point]p=Point(10,20)assertasdict(p)=={'x':10,'y':20}c=C([Point(0,0),Point(10,4)])assertasdict(c)=={'l':[{'x':0,'y':0},{'x':10,'y':4}]}

  RaisesTypeError ifinstance is not a Data Class instance.

• astuple(*,tuple_factory=tuple): Converts the Data Classinstance to a tuple (by using the factory functiontuple_factory). Each Data Class is converted to a tuple of itsfield values. Data Classes, dicts, lists, and tuples are recursedinto.

  Continuing from the previous example:

  assertastuple(p)==(10,20)assertastuple(c)==([(0,0),(10,4)],)

  RaisesTypeError ifinstance is not a Data Class instance.

• make_dataclass(cls_name,fields,*,bases=(),namespace=None):Creates a new Data Class with namecls_name, fields as definedinfields, base classes as given inbases, and initializedwith a namespace as given innamespace.fields is aniterable whose elements are eithername,(name,type), or(name,type,Field). If justname is supplied,typing.Any is used fortype. This function is not strictlyrequired, because any Python mechanism for creating a new class with__annotations__ can then apply thedataclass function toconvert that class to a Data Class. This function is provided as aconvenience. For example:

  C=make_dataclass('C',[('x',int),'y',('z',int,field(default=5))],namespace={'add_one':lambdaself:self.x+1})

  Is equivalent to:

  @dataclassclassC:x:inty:'typing.Any'z:int=5defadd_one(self):returnself.x+1

• replace(instance,**changes): Creates a new object of the sametype ofinstance, replacing fields with values fromchanges.Ifinstance is not a Data Class, raisesTypeError. Ifvalues inchanges do not specify fields, raisesTypeError.

  The newly returned object is created by calling the__init__method of the Data Class. This ensures that__post_init__, if present, is also called.

  Init-only variables without default values, if any exist, must bespecified on the call toreplace so that they can be passed to__init__ and__post_init__.

  It is an error forchanges to contain any fields that aredefined as havinginit=False. AValueError will be raisedin this case.

  Be forewarned about howinit=False fields work during a call toreplace(). They are not copied from the source object, butrather are initialized in__post_init__(), if they’reinitialized at all. It is expected thatinit=False fields willbe rarely and judiciously used. If they are used, it might be wiseto have alternate class constructors, or perhaps a customreplace() (or similarly named) method which handles instancecopying.

• is_dataclass(class_or_instance): Returns True if its parameteris a dataclass or an instance of one, otherwise returns False.

  If you need to know if a class is an instance of a dataclass (andnot a dataclass itself), then add a further check fornotisinstance(obj,type):

  defis_dataclass_instance(obj):returnis_dataclass(obj)andnotisinstance(obj,type)

python-ideas discussion

This discussion started on python-ideas[9] and was moved to a GitHubrepo[10] for further discussion. As part of this discussion, we madethe decision to usePEP 526 syntax to drive the discovery of fields.

Support for automatically setting__slots__?

At least for the initial release,__slots__ will not be supported.__slots__ needs to be added at class creation time. The DataClass decorator is called after the class is created, so in order toadd__slots__ the decorator would have to create a new class, set__slots__, and return it. Because this behavior is somewhatsurprising, the initial version of Data Classes will not supportautomatically setting__slots__. There are a number ofworkarounds:

• Manually add__slots__ in the class definition.
• Write a function (which could be used as a decorator) that inspectsthe class usingfields() and creates a new class with__slots__ set.

For more discussion, see[11].

Why not just use namedtuple?

• Any namedtuple can be accidentally compared to any other with thesame number of fields. For example:Point3D(2017,6,2)==Date(2017,6,2). With Data Classes, this would return False.
• A namedtuple can be accidentally compared to a tuple. For example,Point2D(1,10)==(1,10). With Data Classes, this would returnFalse.
• Instances are always iterable, which can make it difficult to addfields. If a library defines:

  Time=namedtuple('Time',['hour','minute'])defget_time():returnTime(12,0)

  Then if a user uses this code as:

  hour,minute=get_time()

  then it would not be possible to add asecond field toTimewithout breaking the user’s code.

• No option for mutable instances.
• Cannot specify default values.
• Cannot control which fields are used for__init__,__repr__,etc.
• Cannot support combining fields by inheritance.

Why not just use typing.NamedTuple?

For classes with statically defined fields, it does support similarsyntax to Data Classes, using type annotations. This produces anamedtuple, so it sharesnamedtuples benefits and some of itsdownsides. Data Classes, unliketyping.NamedTuple, supportcombining fields via inheritance.

Why not just use attrs?

• attrs moves faster than could be accommodated if it were moved in tothe standard library.
• attrs supports additional features not being proposed here:validators, converters, metadata, etc. Data Classes makes atradeoff to achieve simplicity by not implementing thesefeatures.

For more discussion, see[12].

post-init parameters

In an earlier version of this PEP beforeInitVar was added, thepost-init function__post_init__ never took any parameters.

The normal way of doing parameterized initialization (and not justwith Data Classes) is to provide an alternate classmethod constructor.For example:

@dataclassclassC:x:int@classmethoddeffrom_file(cls,filename):withopen(filename)asfl:file_value=int(fl.read())returnC(file_value)c=C.from_file('file.txt')

Because the__post_init__ function is the last thing called in thegenerated__init__, having a classmethod constructor (which canalso execute code immediately after constructing the object) isfunctionally equivalent to being able to pass parameters to a__post_init__ function.

WithInitVars,__post_init__ functions can now takeparameters. They are passed first to__init__ which passes themto__post_init__ where user code can use them as needed.

The only real difference between alternate classmethod constructorsandInitVar pseudo-fields is in regards to required non-fieldparameters during object creation. WithInitVars, using__init__ and the module-levelreplace() functionInitVarsmust always be specified. Consider the case where acontextobject is needed to create an instance, but isn’t stored as a field.With alternate classmethod constructors thecontext parameter isalways optional, because you could still create the object by goingthrough__init__ (unless you suppress its creation). Whichapproach is more appropriate will be application-specific, but bothapproaches are supported.

Another reason for usingInitVar fields is that the class authorcan control the order of__init__ parameters. This is especiallyimportant with regular fields andInitVar fields that have defaultvalues, as all fields with defaults must come after all fields withoutdefaults. A previous design had all init-only fields coming afterregular fields. This meant that if any field had a default value,then all init-only fields would have to have defaults values, too.

asdict and astuple function names

The names of the module-level helper functionsasdict() andastuple() are arguably notPEP 8 compliant, and should beas_dict() andas_tuple(), respectively. However, afterdiscussion[13] it was decided to keep consistency withnamedtuple._asdict() andattr.asdict().

Copyinginit=False fields after new object creation in replace()

Fields that areinit=False are by definition not passed to__init__, but instead are initialized with a default value, or bycalling a default factory function in__init__, or by code in__post_init__.

A previous version of this PEP specified thatinit=False fieldswould be copied from the source object to the newly created objectafter__init__ returned, but that was deemed to be inconsistentwith using__init__ and__post_init__ to initialize the newobject. For example, consider this case:

@dataclassclassSquare:length:floatarea:float=field(init=False,default=0.0)def__post_init__(self):self.area=self.length*self.lengths1=Square(1.0)s2=replace(s1,length=2.0)

Ifinit=False fields were copied from the source to thedestination object after__post_init__ is run, then s2 would endup beginSquare(length=2.0,area=1.0), instead of the correctSquare(length=2.0,area=4.0).

Automatically support mutable default values

One proposal was to automatically copy defaults, so that if a literallist[] was a default value, each instance would get a new list.There were undesirable side effects of this decision, so the finaldecision is to disallow the 3 known built-in mutable types: list,dict, and set. For a complete discussion of this and other options,see[14].

Custom __init__ method

Sometimes the generated__init__ method does not suffice. Forexample, suppose you wanted to have an object to store*args and**kwargs:

@dataclass(init=False)classArgHolder:args:List[Any]kwargs:Mapping[Any,Any]def__init__(self,*args,**kwargs):self.args=argsself.kwargs=kwargsa=ArgHolder(1,2,three=3)

A complicated example

This code exists in a closed source project:

classApplication:def__init__(self,name,requirements,constraints=None,path='',executable_links=None,executables_dir=()):self.name=nameself.requirements=requirementsself.constraints={}ifconstraintsisNoneelseconstraintsself.path=pathself.executable_links=[]ifexecutable_linksisNoneelseexecutable_linksself.executables_dir=executables_dirself.additional_items=[]def__repr__(self):returnf'Application({self.name!r},{self.requirements!r},{self.constraints!r},{self.path!r},{self.executable_links!r},{self.executables_dir!r},{self.additional_items!r})'

This can be replaced by:

@dataclassclassApplication:name:strrequirements:List[Requirement]constraints:Dict[str,str]=field(default_factory=dict)path:str=''executable_links:List[str]=field(default_factory=list)executable_dir:Tuple[str]=()additional_items:List[str]=field(init=False,default_factory=list)

The Data Class version is more declarative, has less code, supportstyping, and includes the other generated functions.