Most classes you’ll define provide an __init__ method to create and initialize an object’s attributes and a __repr__ method to specify an object’s custom string representation. If a class has many data attributes, creating these methods can be tedious.

Data classes autogenerate the data attributes and the __init__ and __repr__ methods for you. This can be particularly useful for classes that primarily aggregate related data items. For example, in an application that processes CSV records, you might want a class that represents each record’s fields as data attributes in an object. You’ll see in an exercise that data classes can be generated dynamically from a list of field names.

Data classes also autogenerate method __eq__, which overloads the == operator. Any class that has an __eq__ method also implicitly supports !=. All classes inherit class object’s default __ne__ (not equals) method implementation, which returns the opposite of __eq__ (or NotImplemented if the class does not define __eq__). Data classes do not automatically generate methods for the <, <=, > and >= comparison operators, but they can.

The Python Standard Library’s dataclasses module defines decorators and functions for implementing data classes. We’ll use the @dataclass decorator (imported at line 4) to specify that a new class is a data class and causes various code to be written for you. Recall that our original Card class defined class variables FACES and SUITS, which are lists of the strings used to initialize Cards. We use ClassVar and List from the Python Standard Library’s typing module (imported at line 5) to indicate that FACES and SUITS are class variables that refer to lists. We’ll say more about these momentarily:

1 # carddataclass.py
2 """Card data class with class attributes, data attributes,
3 autogenerated methods and explicitly defined methods."""
4 from dataclasses import dataclass
5 from typing import ClassVar, List
6

To specify that a class is a data class, precede its definition with the @dataclass decorator:¹³

7 @dataclass
8 class Card:

Optionally, the @dataclass decorator may specify parentheses containing arguments that help the data class determine what autogenerated methods to include. For example, the decorator @dataclass(order=True) would cause the data class to autogenerate overloaded comparison operator methods for <, <=, > and >=. This might be useful, for example, if you need to sort your data-class objects.

Unlike regular classes, data classes declare both class attributes and data attributes inside the class, but outside the class’s methods. In a regular class, only class attributes are declared this way, and data attributes typically are created in __init__. Data classes require additional information, or hints, to distinguish class attributes from data attributes, which also affects the autogenerated methods’ implementation details.

Lines 9–11 define and initialize the class attributes FACES and SUITS:

 9 FACES: ClassVar[List[str]] = ['Ace', '2', '3', '4', '5', '6', '7',
10                               '8', '9', '10', 'Jack', 'Queen', 'King']
11 SUITS: ClassVar[List[str]] = ['Hearts', 'Diamonds', 'Clubs', 'Spades']
12

In lines 9 and 11, The notation

         : ClassVar[List[str]]

is a variable annotation¹⁴ _,¹⁵ (sometimes called a type hint) specifying that FACES is a class attribute (ClassVar) which refers to a list of strings (List[str]). SUITS also is a class attribute which refers to a list of strings.

Class variables are initialized in their definitions and are specific to the class, not individual objects of the class. Methods __init__, __repr__ and __eq__, however, are for use with objects of the class. When a data class generates these methods, it inspects all the variable annotations and includes only the data attributes in the method implementations.

Normally, we create an object’s data attributes in the class’s __init__ method (or methods called by __init__) via assignments of the form self.attribute_name = value. Because a data class autogenerates its __init__ method, we need another way to specify data attributes in a data class’s definition. We cannot simply place their names inside the class, which generates a NameError, as in:

In [1]: from dataclasses import dataclass

In [2]: @dataclass
   ...: class Demo:
   ...:     x # attempting to create a data attribute x
   ...:
-------------------------------------------------------------------------
NameError                               Traceback (most recent call last)
<ipython-input-2-79ffe37b1ba2> in <module>()
----> 1 @dataclass
      2 class Demo:
      3     x # attempting to create a data attribute x
      4

<ipython-input-2-79ffe37b1ba2> in Demo()
      1 @dataclass
      2 class Demo:
----> 3     x # attempting to create a data attribute x
      4
NameError: name 'x' is not defined

Like class attributes, each data attribute must be declared with a variable annotation. Lines 13–14 define the data attributes face and suit. The variable annotation ": str" indicates that each should refer to string objects:

13   face: str
14   suit: str

Data classes are classes, so they may contain properties and methods and participate in class hierarchies. For this Card data class, we defined the same read-only image_name property and custom special methods __str__ and __format__ as in our original Card class earlier in the chapter:

15    @property
16    def image_name(self):
17        """Return the Card's image file name."""
18        return str(self).replace(' ', '_') + '.png'
19
20    def __str__(self):
21        """Return string representation for str()."""
22        return f'{self.face} of {self.suit}'
23
24    def __format__(self, format):
25        """Return formatted string representation."""
26        return f'{str(self):{format}}'

You can specify variable annotations using built-in type names (like str, int and float), class types or types defined by the typing module (such as ClassVar and List shown earlier). Even with type annotations, Python is still a dynamically typed language. So, type annotations are not enforced at execution time. So, even though a Card’s face is meant to be a string, you can assign any type of object to face, as you’ll do in a Self Check exercise.

Data classes have additional capabilities, such as creating “frozen” instances which do not allow you to assign values to a data class object’s attributes after the object is created. For a complete list of data class benefits and capabilities, see

and

We’ll ask you to experiment with additional data class features in this chapter’s exercises.