How to use Python dataclasses

Everything in Python is an object, or so the saying goes. If you want to create your own custom objects, with their own properties and methods, you use Python’s class object to make that happen. But creating classes in Python sometimes means writing loads of repetitive, boilerplate code to set up the class instance from the parameters passed to it or to create common functions like comparison operators.

Dataclasses, introduced in Python 3.7 (and backported to Python 3.6), provide a handy, less verbose way to create classes. Many of the common things you do in a class, like instantiating properties from the arguments passed to the class, can be reduced to a few basic instructions.

Python dataclass example

Here is a simple example of a conventional class in Python:

class Book:
    '''Object for tracking physical books in a collection.'''
    def __init__(self, name: str, weight: float, shelf_id:int = 0):
        self.name = name
        self.weight = weight # in grams, for calculating shipping
        self.shelf_id = shelf_id
    def __repr__(self):
        return(f"Book(name={self.name!r},
            weight={self.weight!r}, shelf_id={self.shelf_id!r})")

The biggest headache here is the way each of the arguments passed to __init__ has to be copied to the object’s properties. This isn’t so bad if you’re only dealing with Book, but what if you have to deal with  Bookshelf, Library, Warehouse, and so on? Plus, the more code you have to type by hand, the greater the chances you’ll make a mistake.

Here is the same Python class, implemented as a Python dataclass:

from dataclasses import dataclass

@dataclass
class Book:
    '''Object for tracking physical books in a collection.'''
    name: str
    weight: float 
    shelf_id: int = 0

When you specify properties, called fields, in a dataclass, the @dataclass decorator automatically generates all of the code needed to initialize them. It also preserves the type information for each property, so if you use a code linter like mypy, it will ensure that you’re supplying the right kinds of variables to the class constructor.

Another thing @dataclass does behind the scenes is automatically create code for a number of common dunder methods in the class. In the conventional class above, we had to create our own __repr__. In the dataclass, the @dataclass decorator generates the __repr__ for you.

Once a dataclass is created it is functionally identical to a regular class. There is no performance penalty for using a dataclass. There's only a small performance penalty for declaring the class as a dataclass, and that's a one-time cost when the dataclass object is created.

Advanced Python dataclass initialization

The dataclass decorator can take initialization options of its own. Most of the time you won't need to supply them, but they can come in handy for certain edge cases. Here are some of the most useful ones (they're all True/False):

• frozen: Generates class instances that are read-only. Once data has been assigned, it can't be modified.
• slots: Allows instances of dataclasses to use less memory by only allowing fields explicitly defined in the class.
• kw_only: When set, all fields for the class are keyword-only.

Customize Python dataclass fields with the field function

The default way dataclasses work should be okay for the majority of use cases. Sometimes, though, you need to fine-tune how the fields in your dataclass are initialized. As shown below, you can use the field function for fine-tuning:

from dataclasses import dataclass, field
from typing import List

@dataclass
class Book:
    '''Object for tracking physical books in a collection.'''
    name: str     
    condition: str = field(compare=False)    
    weight: float = field(default=0.0, repr=False)
    shelf_id: int = 0
    chapters: List[str] = field(default_factory=list)

When you set a default value to an instance of field, it changes how the field is set up depending on what parameters you give field. These are the most commonly used options for field (there are others):

• default: Sets the default value for the field. You need to use default if you a) use field to change any other parameters for the field, and b) want to set a default value on the field on top of that. In this case, we use default to set weight to 0.0.
• default_factory: Provides the name of a function, which takes no parameters, that returns some object to serve as the default value for the field. In this case, we want chapters to be an empty list.
• repr: By default (True), controls if the field in question shows up in the automatically generated __repr__ for the dataclass. In this case we don’t want the book’s weight shown in the __repr__, so we use repr=False to omit it.
• compare: By default (True), includes the field in the comparison methods automatically generated for the dataclass. Here, we don’t want condition to be used as part of the comparison for two books, so we set compare=False.

Note that we have had to adjust the order of the fields so that the non-default fields come first.

Controlling Python dataclass initialization

At this point you’re probably wondering: If the __init__ method of a dataclass is generated automatically, how do I get control over the init process to make more fine-grained changes?

__post_init__

Enter the __post_init__ method. If you include the __post_init__ method in your dataclass definition, you can provide instructions for modifying fields or other instance data:

from dataclasses import dataclass, field
from typing import List

@dataclass
class Book:
    '''Object for tracking physical books in a collection.'''
    name: str    
    weight: float = field(default=0.0, repr=False)
    shelf_id: Optional[int] = field(init=False)
    chapters: List[str] = field(default_factory=list)
    condition: str = field(default="Good", compare=False)

    def __post_init__(self):
        if self.condition == "Discarded":
            self.shelf_id = None
        else:
            self.shelf_id = 0

In this example, we have created a __post_init__ method to set shelf_id to None if the book’s condition is initialized as "Discarded". Note how we use field to initialize shelf_id, and pass init as False to field. This means shelf_id won’t be initialized in __init__.

InitVar

Another way to customize Python dataclass setup is to use the InitVar type. This lets you specify a field that will be passed to __init__ and then to __post_init__, but won’t be stored in the class instance.

By using InitVar, you can take in parameters when setting up the dataclass that are only used during initialization. Here's an example:

from dataclasses import dataclass, field, InitVar
from typing import List

@dataclass
class Book:
    '''Object for tracking physical books in a collection.'''
    name: str     
    condition: InitVar[str] = "Good"
    weight: float = field(default=0.0, repr=False)
    shelf_id: int = field(init=False)
    chapters: List[str] = field(default_factory=list)

    def __post_init__(self, condition):
        if condition == "Unacceptable":
            self.shelf_id = None
        else:
            self.shelf_id = 0

Setting a field’s type to InitVar (with its subtype being the actual field type) signals to @dataclass to not make that field into a dataclass field, but to pass the data along to __post_init__ as an argument.

In this version of our Book class, we’re not storing condition as a field in the class instance. We’re only using condition during the initialization phase. If we find that condition was set to "Unacceptable", we set shelf_id to None — but we don’t store condition itself in the class instance.

When to use Python dataclasses—and when not to use them

One common scenario for using dataclasses is as a replacement for the namedtuple. Dataclasses offer the same behaviors and more, and they can be made immutable (as namedtuples are) by simply using @dataclass(frozen=True) as the decorator.

Another possible use case is replacing nested dictionaries, which can be clumsy to work with, with nested instances of dataclasses. If you have a dataclass Library, with a list property of shelves, you could use a dataclass ReadingRoom to populate that list, then add methods to make it easy to access nested items (e.g., a book on a shelf in a particular room).

But not every Python class needs to be a dataclass. If you’re creating a class mainly as a way to group together a bunch of static methods, rather than as a container for data, you don’t need to make it a dataclass. For instance, a common pattern with parsers is to have a class that takes in an abstract syntax tree, walks the tree, and dispatches calls to different methods in the class based on the node type. Because the parser class has very little data of its own, a dataclass isn’t useful here.