Python’s Dataclass in a Nutshell

SincePython 3.7, Python ships with the@dataclassdecorator that allows you to create data classes. A data class is a class typically containing mainly data, although there aren’t really any restrictions. You create it using the@dataclass decorator, as follows:

fromdataclassesimportdataclass@dataclassclassDataClassCard:rank:strsuit:str

A data class comes with basic functionality already implemented. For instance, you can instantiate, print, and compare data class instances straight out of the box:

>>>queen_of_hearts=DataClassCard('Q','Hearts')>>>queen_of_hearts.rank'Q'>>>queen_of_heartsDataClassCard(rank='Q', suit='Hearts')>>>queen_of_hearts==DataClassCard('Q','Hearts')True

Compare that to a regular class. A minimal regular class would look something like this:

classRegularCard:def__init__(self,rank,suit):self.rank=rankself.suit=suit

While this is not much more code to write, you can already see signs of the boilerplate pain:rank andsuit are both repeated three times simply to initialize an object. Furthermore, if you try to use this plain class, you’ll notice that the representation of the objects is not very descriptive, and for some reason a queen of hearts is not the same as a queen of hearts:

>>>queen_of_hearts=RegularCard('Q','Hearts')>>>queen_of_hearts.rank'Q'>>>queen_of_hearts<__main__.RegularCard object at 0x7fb6eee35d30>>>>queen_of_hearts==RegularCard('Q','Hearts')False

Seems like data classes are helping us out behind the scenes. By default, data classes implement a.__repr__() method to provide a nice string representation and an.__eq__() method that can do basic object comparisons. For theRegularCard class to imitate the data class above, you need to add these methods as well:

classRegularCarddef__init__(self,rank,suit):self.rank=rankself.suit=suitdef__repr__(self):return(f'{self.__class__.__name__}'f'(rank={self.rank!r}, suit={self.suit!r})')def__eq__(self,other):ifother.__class__isnotself.__class__:returnNotImplementedreturn(self.rank,self.suit)==(other.rank,other.suit)

In this tutorial, you’ll learn exactly which conveniences data classes provide. In addition to nice representations and comparisons, you’ll see:

• How to add default values to data class fields
• How data classes allow for ordering of objects
• How to represent immutable data
• How data classes handle inheritance

You’ll soon dive deeper into those features of data classes. However, you might be thinking that you have already seen something like this before. And indeed, there are similar constructs in Python that you can revisit in the next section.

Alternatives to Data Classes

For simple data structures, you have probably already usedatuple or adict. You could represent the queen of hearts card in either of the following ways:

>>>queen_of_hearts_tuple=('Q','Hearts')>>>queen_of_hearts_dict={'rank':'Q','suit':'Hearts'}

It works. However, it puts a lot of responsibility on you as a programmer:

• You need to remember that thequeen_of_hearts_...variable represents a card.
• For thetuple version, you need to remember the order of the attributes. Writing('Spades', 'A') will mess up your program but probably not give you an easily understandable error message.
• If you use thedict version, you must make sure the names of the attributes are consistent. For instance{'value': 'A', 'suit': 'Spades'} will not work as expected.

Furthermore, using these structures is not ideal:

>>>queen_of_hearts_tuple[0]# No named access'Q'>>>queen_of_hearts_dict['suit']# Would be nicer with .suit'Hearts'

A better alternative is thenamedtuple. It has long been used to create readable small data structures. We can in fact recreate the data class example above using anamedtuple like this:

fromcollectionsimportnamedtupleNamedTupleCard=namedtuple('NamedTupleCard',['rank','suit'])

This definition ofNamedTupleCard will give the exact same output as ourDataClassCard example did:

>>>queen_of_hearts=NamedTupleCard('Q','Hearts')>>>queen_of_hearts.rank'Q'>>>queen_of_heartsNamedTupleCard(rank='Q', suit='Hearts')>>>queen_of_hearts==NamedTupleCard('Q','Hearts')True

So why even bother with data classes? First of all, data classes come with many more features than you have seen so far. At the same time, thenamedtuple has some other features that are not necessarily desirable. By design, anamedtuple is a regular tuple. This can be seen in comparisons, for instance:

>>>queen_of_hearts==('Q','Hearts')True

While this might seem like a good thing, this lack of awareness about its own type can lead to subtle and hard-to-find bugs, especially since it will also happily compare two differentnamedtuple classes:

>>>Person=namedtuple('Person',['first_initial','last_name']>>>ace_of_spades=NamedTupleCard('A','Spades')>>>ace_of_spades==Person('A','Spades')True

Thenamedtuple also comes with some restrictions. For instance, it is hard to add default values to some of the fields in anamedtuple. Anamedtuple is also by natureimmutable. That is, the value of anamedtuple can never change. In some applications, this is an awesome feature, but in other settings, it would be nice to have more flexibility:

>>>card=NamedTupleCard('7','Diamonds')>>>card.rank='9'AttributeError: can't set attribute

Data classes will not replace all uses ofnamedtuple. For instance, if you need your data structure to behave like a tuple, then a named tuple is a great alternative!

Another alternative, and one of theinspirations for data classes, is theattrs project. Withattrs installed (pip install attrs), you can write a card class as follows:

importattr@attr.sclassAttrsCard:rank=attr.ib()suit=attr.ib()

This can be used in exactly the same way as theDataClassCard andNamedTupleCard examples earlier. Theattrs project is great and does support some features that data classes do not, including converters and validators. Furthermore,attrs has been around for a while and is supported in Python 2.7 as well as Python 3.4 and up. However, asattrs is not a part of the standard library, it does add an externaldependency to your projects. Through data classes, similar functionality will be available everywhere.

In addition totuple,dict,namedtuple, andattrs, there aremany other similar projects, includingtyping.NamedTuple,namedlist,attrdict,plumber, andfields. While data classes are a great alternative, there are still use cases where one of the other variants fits better. For instance, if you need compatibility with a specific API expecting tuples or need functionality not supported in data classes.

Basic Data Classes

Let us get back to data classes. As an example, we will create aPosition class that will represent geographic positions with a name as well as the latitude and longitude:

fromdataclassesimportdataclass@dataclassclassPosition:name:strlon:floatlat:float

What makes this a data class is the@dataclass decorator just above the class definition. Beneath theclass Position: line, you simply list the fields you want in your data class. The: notation used for the fields is using a feature calledvariable annotations. We willsoon talk more about this notation and why we specify data types likestr andfloat.

Those few lines of code are all you need. The new class is ready for use:

>>>pos=Position('Oslo',10.8,59.9)>>>print(pos)Position(name='Oslo', lon=10.8, lat=59.9)>>>pos.lat59.9>>>print(f'{pos.name} is at{pos.lat}°N,{pos.lon}°E')Oslo is at 59.9°N, 10.8°E

You can also create data classes similarly to how named tuples are created. The following is (almost) equivalent to the definition ofPosition above:

fromdataclassesimportmake_dataclassPosition=make_dataclass('Position',['name','lat','lon'])

A data class is a regularPython class. The only thing that sets it apart is that it has basicdata model methods like.__init__(),.__repr__(), and.__eq__() implemented for you.

fromdataclassesimportdataclass@dataclassclassPosition:name:strlon:float=0.0lat:float=0.0

>>>Position('Null Island')Position(name='Null Island', lon=0.0, lat=0.0)>>>Position('Greenwich',lat=51.8)Position(name='Greenwich', lon=0.0, lat=51.8)>>>Position('Vancouver',-123.1,49.3)Position(name='Vancouver', lon=-123.1, lat=49.3)

fromdataclassesimportdataclassfromtypingimportAny@dataclassclassWithoutExplicitTypes:name:Anyvalue:Any=42

>>>Position(3.14,'pi day',2018)Position(name=3.14, lon='pi day', lat=2018)

Adding Methods

You already know that a data class is just a regular class. That means that you can freely add your own methods to a data class. As an example, let us calculate the distance between one position and another, along the Earth’s surface. One way to do this is by usingthe haversine formula:

You can add a.distance_to() method to your data class just like you can with normal classes:

Python

fromdataclassesimportdataclassfrommathimportasin,cos,radians,sin,sqrt@dataclassclassPosition:name:strlon:float=0.0lat:float=0.0defdistance_to(self,other):r=6371# Earth radius in kilometerslam_1,lam_2=radians(self.lon),radians(other.lon)phi_1,phi_2=radians(self.lat),radians(other.lat)h=(sin((phi_2-phi_1)/2)**2+cos(phi_1)*cos(phi_2)*sin((lam_2-lam_1)/2)**2)return2*r*asin(sqrt(h))

It works as you would expect:

Python

>>>oslo=Position('Oslo',10.8,59.9)>>>vancouver=Position('Vancouver',-123.1,49.3)>>>oslo.distance_to(vancouver)7181.7841229421165

More Flexible Data Classes

So far, you have seen some of the basic features of the data class: it gives you some convenience methods, and you can still add default values and other methods. Now you will learn about some more advanced features like parameters to the@dataclass decorator and thefield() function. Together, they give you more control when creating a data class.

Let us return to the playing card example you saw at the beginning of the tutorial and add a class containing a deck of cards while we are at it:

fromdataclassesimportdataclassfromtypingimportList@dataclassclassPlayingCard:rank:strsuit:str@dataclassclassDeck:cards:List[PlayingCard]

A simple deck containing only two cards can be created like this:

>>>queen_of_hearts=PlayingCard('Q','Hearts')>>>ace_of_spades=PlayingCard('A','Spades')>>>two_cards=Deck([queen_of_hearts,ace_of_spades])Deck(cards=[PlayingCard(rank='Q', suit='Hearts'),            PlayingCard(rank='A', suit='Spades')])

RANKS='2 3 4 5 6 7 8 9 10 J Q K A'.split()SUITS='♣ ♢ ♡ ♠'.split()defmake_french_deck():return[PlayingCard(r,s)forsinSUITSforrinRANKS]

>>>make_french_deck()[PlayingCard(rank='2', suit='♣'), PlayingCard(rank='3', suit='♣'), ... PlayingCard(rank='K', suit='♠'), PlayingCard(rank='A', suit='♠')]

fromdataclassesimportdataclassfromtypingimportList@dataclassclassDeck:# Will NOT workcards:List[PlayingCard]=make_french_deck()

fromdataclassesimportdataclass,fieldfromtypingimportList@dataclassclassDeck:cards:List[PlayingCard]=field(default_factory=make_french_deck)

>>>Deck()Deck(cards=[PlayingCard(rank='2', suit='♣'), PlayingCard(rank='3', suit='♣'), ...            PlayingCard(rank='K', suit='♠'), PlayingCard(rank='A', suit='♠')])

fromdataclassesimportdataclass,field@dataclassclassPosition:name:strlon:float=field(default=0.0,metadata={'unit':'degrees'})lat:float=field(default=0.0,metadata={'unit':'degrees'})

>>>fromdataclassesimportfields>>>fields(Position)(Field(name='name',type=<class 'str'>,...,metadata={}), Field(name='lon',type=<class 'float'>,...,metadata={'unit': 'degrees'}), Field(name='lat',type=<class 'float'>,...,metadata={'unit': 'degrees'}))>>>lat_unit=fields(Position)[2].metadata['unit']>>>lat_unit'degrees'

>>>Deck()Deck(cards=[PlayingCard(rank='2', suit='♣'), PlayingCard(rank='3', suit='♣'), ...            PlayingCard(rank='K', suit='♠'), PlayingCard(rank='A', suit='♠')])

fromdataclassesimportdataclass@dataclassclassPlayingCard:rank:strsuit:strdef__str__(self):returnf'{self.suit}{self.rank}'

>>>ace_of_spades=PlayingCard('A','♠')>>>ace_of_spadesPlayingCard(rank='A', suit='♠')>>>print(ace_of_spades)♠A>>>print(Deck())Deck(cards=[PlayingCard(rank='2', suit='♣'), PlayingCard(rank='3', suit='♣'), ...            PlayingCard(rank='K', suit='♠'), PlayingCard(rank='A', suit='♠')])

fromdataclassesimportdataclass,fieldfromtypingimportList@dataclassclassDeck:cards:List[PlayingCard]=field(default_factory=make_french_deck)def__repr__(self):cards=', '.join(f'{c!s}'forcinself.cards)returnf'{self.__class__.__name__}({cards})'

>>>Deck()Deck(♣2, ♣3, ♣4, ♣5, ♣6, ♣7, ♣8, ♣9, ♣10, ♣J, ♣Q, ♣K, ♣A,     ♢2, ♢3, ♢4, ♢5, ♢6, ♢7, ♢8, ♢9, ♢10, ♢J, ♢Q, ♢K, ♢A,     ♡2, ♡3, ♡4, ♡5, ♡6, ♡7, ♡8, ♡9, ♡10, ♡J, ♡Q, ♡K, ♡A,     ♠2, ♠3, ♠4, ♠5, ♠6, ♠7, ♠8, ♠9, ♠10, ♠J, ♠Q, ♠K, ♠A)

>>>queen_of_hearts=PlayingCard('Q','♡')>>>ace_of_spades=PlayingCard('A','♠')>>>ace_of_spades>queen_of_heartsTypeError: '>' not supported between instances of 'Card' and 'Card'

fromdataclassesimportdataclass@dataclass(order=True)classPlayingCard:rank:strsuit:strdef__str__(self):returnf'{self.suit}{self.rank}'

>>>queen_of_hearts=PlayingCard('Q','♡')>>>ace_of_spades=PlayingCard('A','♠')>>>ace_of_spades>queen_of_heartsFalse

>>>('A','♠')>('Q','♡')False

>>>RANKS='2 3 4 5 6 7 8 9 10 J Q K A'.split()>>>SUITS='♣ ♢ ♡ ♠'.split()>>>card=PlayingCard('Q','♡')>>>RANKS.index(card.rank)*len(SUITS)+SUITS.index(card.suit)42

fromdataclassesimportdataclass,fieldRANKS='2 3 4 5 6 7 8 9 10 J Q K A'.split()SUITS='♣ ♢ ♡ ♠'.split()@dataclass(order=True)classPlayingCard:sort_index:int=field(init=False,repr=False)rank:strsuit:strdef__post_init__(self):self.sort_index=(RANKS.index(self.rank)*len(SUITS)+SUITS.index(self.suit))def__str__(self):returnf'{self.suit}{self.rank}'

>>>queen_of_hearts=PlayingCard('Q','♡')>>>ace_of_spades=PlayingCard('A','♠')>>>ace_of_spades>queen_of_heartsTrue

>>>Deck(sorted(make_french_deck()))Deck(♣2, ♢2, ♡2, ♠2, ♣3, ♢3, ♡3, ♠3, ♣4, ♢4, ♡4, ♠4, ♣5,     ♢5, ♡5, ♠5, ♣6, ♢6, ♡6, ♠6, ♣7, ♢7, ♡7, ♠7, ♣8, ♢8,     ♡8, ♠8, ♣9, ♢9, ♡9, ♠9, ♣10, ♢10, ♡10, ♠10, ♣J, ♢J, ♡J,     ♠J, ♣Q, ♢Q, ♡Q, ♠Q, ♣K, ♢K, ♡K, ♠K, ♣A, ♢A, ♡A, ♠A)

>>>fromrandomimportsample>>>Deck(sample(make_french_deck(),k=10))Deck(♢2, ♡A, ♢10, ♣2, ♢3, ♠3, ♢A, ♠8, ♠9, ♠2)

Immutable Data Classes

One of the defining features of thenamedtuple you saw earlier is that it isimmutable. That is, the value of its fields may never change. For many types of data classes, this is a great idea! To make a data class immutable, setfrozen=True when you create it. For example, the following is an immutable version of thePosition classyou saw earlier:

fromdataclassesimportdataclass@dataclass(frozen=True)classPosition:name:strlon:float=0.0lat:float=0.0

In a frozen data class, you can not assign values to the fields after creation:

>>>pos=Position('Oslo',10.8,59.9)>>>pos.name'Oslo'>>>pos.name='Stockholm'dataclasses.FrozenInstanceError: cannot assign to field 'name'

Be aware though that if your data class contains mutable fields, those might still change. This is true for all nested data structures in Python (seethis video for further info):

fromdataclassesimportdataclassfromtypingimportList@dataclass(frozen=True)classImmutableCard:rank:strsuit:str@dataclass(frozen=True)classImmutableDeck:cards:List[ImmutableCard]

Even though bothImmutableCard andImmutableDeck are immutable, the list holdingcards is not. You can therefore still change the cards in the deck:

>>>queen_of_hearts=ImmutableCard('Q','♡')>>>ace_of_spades=ImmutableCard('A','♠')>>>deck=ImmutableDeck([queen_of_hearts,ace_of_spades])>>>deckImmutableDeck(cards=[ImmutableCard(rank='Q', suit='♡'), ImmutableCard(rank='A', suit='♠')])>>>deck.cards[0]=ImmutableCard('7','♢')>>>deckImmutableDeck(cards=[ImmutableCard(rank='7', suit='♢'), ImmutableCard(rank='A', suit='♠')])

To avoid this, make sure all fields of an immutable data class use immutable types (but remember that types are not enforced at runtime). TheImmutableDeck should be implemented using a tuple instead of a list.

Inheritance

You cansubclass data classes quite freely. As an example, we will extend ourPosition example with acountry field and use it to record capitals:

fromdataclassesimportdataclass@dataclassclassPosition:name:strlon:floatlat:float@dataclassclassCapital(Position):country:str

In this simple example, everything works without a hitch:

>>>Capital('Oslo',10.8,59.9,'Norway')Capital(name='Oslo', lon=10.8, lat=59.9, country='Norway')

Thecountry field ofCapital is added after the three original fields inPosition. Things get a little more complicated if any fields in the base class have default values:

fromdataclassesimportdataclass@dataclassclassPosition:name:strlon:float=0.0lat:float=0.0@dataclassclassCapital(Position):country:str# Does NOT work

This code will immediately crash with aTypeError complaining that “non-default argument ‘country’ follows default argument.” The problem is that our newcountry field has no default value, while thelon andlat fields have default values. The data class will try to write an.__init__() method with the following signature:

def__init__(name:str,lon:float=0.0,lat:float=0.0,country:str):...

However, this is not valid Python.If a parameter has a default value, all following parameters must also have a default value. In other words, if a field in a base class has a default value, then all new fields added in a subclass must have default values as well.

Another thing to be aware of is how fields are ordered in a subclass. Starting with the base class, fields are ordered in the order in which they are first defined. If a field is redefined in a subclass, its order does not change. For example, if you definePosition andCapital as follows:

fromdataclassesimportdataclass@dataclassclassPosition:name:strlon:float=0.0lat:float=0.0@dataclassclassCapital(Position):country:str='Unknown'lat:float=40.0

Then the order of the fields inCapital will still bename,lon,lat,country. However, the default value oflat will be40.0.

>>>Capital('Madrid',country='Spain')Capital(name='Madrid', lon=0.0, lat=40.0, country='Spain')

Optimizing Data Classes

I’m going to end this tutorial with a few words aboutslots. Slots can be used to make classes faster and use less memory. Data classes have no explicit syntax for working with slots, but the normal way of creating slots works for data classes as well. (They really are just regular classes!)

fromdataclassesimportdataclass@dataclassclassSimplePosition:name:strlon:floatlat:float@dataclassclassSlotPosition:__slots__=['name','lon','lat']name:strlon:floatlat:float

Essentially, slots are defined using.__slots__ to list the variables on a class. Variables or attributes not present in.__slots__ may not be defined. Furthermore, a slots class may not have default values.

The benefit of adding such restrictions is that certain optimizations may be done. For instance, slots classes take up less memory, as can be measured usingPympler:

>>>frompymplerimportasizeof>>>simple=SimplePosition('London',-0.1,51.5)>>>slot=SlotPosition('Madrid',-3.7,40.4)>>>asizeof.asizesof(simple,slot)(440, 248)

Similarly, slots classes are typically faster to work with. The following example measures the speed of attribute access on a slots data class and a regular data class usingtimeit from the standard library.

>>>fromtimeitimporttimeit>>>timeit('slot.name',setup="slot=SlotPosition('Oslo', 10.8, 59.9)",globals=globals())0.05882283499886398>>>timeit('simple.name',setup="simple=SimplePosition('Oslo', 10.8, 59.9)",globals=globals())0.09207444800267695

In this particular example, the slot class is about 35% faster.

Conclusion & Further Reading

Data classes are a convenient feature of Python. With data classes, you don’t have to write boilerplate code to get proper initialization, representation, and comparisons for your objects.

In this tutorial, you’ve learned how to define your own data classes, as well as:

• How to add default values to the fields in your data class
• How to customize the ordering of data class objects
• How to work with immutable data classes
• How inheritance works for data classes

If you want to dive into all the details of data classes, have a look atPEP 557 as well as the discussions in the originalGitHub repo.

In addition, Raymond Hettinger’s PyCon 2018 talkDataclasses: The code generator to end all code generators is well worth watching. And now, go forth and write less code!

Take the Quiz: Test your knowledge with our interactive “Data Classes in Python” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

Data Classes in Python

In this quiz, you'll test your understanding of Python data classes.Data classes, a feature introduced in Python 3.7, are a type of class mainly used for storing data.They come with basic functionality already implemented, such as instance initialization, printing, and comparison.