Python Dataclasses: A Complete Guide

Why You Need Them and How to Use Them for Cleaner, Efficient Code

In this article, we will discuss what Python dataclasses are, why we need them, and how to use them. To understand what these classes are, let’s first start with a simple basic Python class.

A class is just a blueprint for making objects. It encapsulates data (with its attributes) and functions that operate on that data. Keep in mind that Python classes are objects too, just like any other Python object. As with any other object in Python, you can assign a class to a variable, attach attributes to it, and use it as a parameter in other functions.

To clarify, let’s take a look at the following example:

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    def __repr__(self):
        return f"Person(name={self.name}, age={self.age})"

# Creating an instance of Person
person = Person("Alice", 30)
print(person)  # Output: Person(name=Alice, age=30)

As we saw with simple classes, you might notice that if you use classes in Python, you find yourself writing the same code over and over again. You always start by defining your data fields inside the __init__ function, then write other functions like __repr__ or any other method you need. To make that clear, let’s take this example.

Let’s say we want to create a class to represent a Book with attributes like title, author, and year_published. We'll also implement methods for initialization, representation, and comparison.

class Book:
    def __init__(self, title, author, year_published):
        self.title = title
        self.author = author
        self.year_published = year_published

    def __repr__(self):
        return f"Book(title='{self.title}', author='{self.author}', year_published={self.year_published})"

    def __eq__(self, other):
        if isinstance(other, Book):
            return (self.title == other.title and 
                    self.author == other.author and 
                    self.year_published == other.year_published)
        return False

# Creating instances
book1 = Book("1984", "George Orwell", 1949)
book2 = Book("1984", "George Orwell", 1949)

# Comparing instances
print(book1 == book2)  # Output: True

# Printing instance
print(book1)  # Output: Book(title='1984', author='George Orwell', year_published=1949)

You can see that we’re repeating almost the same code as we did in the simple Person class, even with other functions. That’s where dataclasses come in. Introduced in Python 3.7, dataclasses are special types of classes designed to make your work easier by reducing repetitive code and making your codebase cleaner and more readable.

With dataclasses, you can focus on what really matters: defining the data attributes of your class. The @dataclass decorator takes care of generating common methods like __init__, __repr__, and __eq__ for you. This means less time writing boilerplate code and more time focusing on your essential work and features.

To understand that more clearly, let’s create the same Book class using dataclasses. Notice how much cleaner and more concise the code becomes.

from dataclasses import dataclass

@dataclass
class Book:
    title: str
    author: str
    year_published: int

# Creating instances
book1 = Book("1984", "George Orwell", 1949)
book2 = Book("1984", "George Orwell", 1949)

# Comparing instances
print(book1 == book2)  # Output: True

# Printing instance
print(book1)  # Output: Book(title='1984', author='George Orwell', year_published=1949)

You can clearly notice the key differences and benefits:

1. Reduced Boilerplate Code:
   . Without dataclasses, we had to manually implement the __init__, __repr__, and __eq__ methods.
   . With dataclasses, these methods are automatically generated, reducing boilerplate code.
2. Readability:
   . The dataclass version is more concise and easier to read.
   . The class definition focuses on the data attributes, making it clear what the class represents.
3. Automatic Method Generation:
   . dataclasses automatically generate common methods like __init__, __repr__, and __eq__, saving time and reducing the chance of errors.
4. Type Annotations:
   . dataclasses encourage the use of type annotations, improving code readability and helping with static type checking.

Using dataclasses simplifies the creation of classes that are primarily used to store data. They reduce boilerplate code, improve readability, and automatically generate common methods. This makes your code cleaner, more maintainable, and easier to understand. But that’s not all—dataclasses also offer other flexible features, which we will discover in the next section.

In this section, you will discover more about dataclasses. The first feature you may notice in the advantages of using dataclasses is type annotations. Dataclasses use type annotations to define the types of the fields, allowing you to take advantage of type hints and improve code readability.

Next, dataclasses allow you to customize their behavior using various parameters of the dataclass decorator, making your classes even more powerful and flexible. For instance, the init parameter, when set to True (which is the default), generates an __init__() method for your class. This means you don’t have to write the initializer yourself.

from dataclasses import dataclass

@dataclass(init=True)
class Person:
    name: str
    age: int

# Creating an instance
person = Person("Alice", 30)
print(person)  # Output: Person(name='Alice', age=30)

Similarly, the repr parameter, also True by default, generates a __repr__() method. This provides a readable string representation of your object, which is super handy for debugging.

@dataclass(repr=True)
class Person:
    name: str
    age: int

# Creating an instance
person = Person("Alice", 30)
print(person)  # Output: Person(name='Alice', age=30)

Also, there is the eq parameter, as you might guess, set to True by default, which generates an __eq__() method. This allows you to compare instances of your class based on their attributes.

@dataclass(eq=True)
class Person:
    name: str
    age: int

# Comparing instances
person1 = Person("Alice", 30)
person2 = Person("Alice", 30)
print(person1 == person2)  # Output: True

The order parameter, when set to True, generates comparison methods (__lt__, __le__, __gt__, __ge__). This is useful for sorting and ordering instances.

@dataclass(order=True)
class Person:
    name: str
    age: int

# Comparing instances
person1 = Person("Alice", 30)
person2 = Person("Bob", 25)
print(person1 > person2)  # Output: True

So, there is also the unsafe_hash parameter, which, when set to True, generates a __hash__() method. This allows instances of your class to be used in hash-based collections like sets and dictionaries.

@dataclass(unsafe_hash=True)
class Person:
    name: str
    age: int

# Using instances in a set
person1 = Person("Alice", 30)
person2 = Person("Bob", 25)
people = {person1, person2}
print(people)

In the above example, you notice that we are now able to use the instances of the Person class in a set collection, which previously would have caused errors.

Now, sometimes you may want to make your class immutable. This means that once an instance is created, its attributes cannot be changed. This is where you may find the frozen parameter useful. When set to True, it makes your class immutable.

@dataclass(frozen=True)
class Person:
    name: str
    age: int

# Creating an instance
person = Person("Alice", 30)
# person.age = 31  # This will raise an error

Along with that, there are still some other parameters you can use to further customize the behavior of your dataclasses. Let’s go through those quickly:

The match_args parameter, set to True by default, generates the __match_args__ attribute. This is useful for pattern matching in Python 3.10 and later.

@dataclass(match_args=True)
class Person:
    name: str
    age: int

# Using match_args in pattern matching (Python 3.10+)
person = Person("Alice", 30)
match person:
    case Person(name, age):
        print(f"Name: {name}, Age: {age}")

Next, the kw_only parameter, when set to True, requires all fields to be specified as keyword arguments. This enhances clarity and readability.

@dataclass(kw_only=True)
class Person:
    name: str
    age: int

# Creating an instance
person = Person(name="Alice", age=30)

The slots parameter, when set to True, uses __slots__ to reduce memory usage by preventing the creation of __dict__ for each instance.

@dataclass(slots=True)
class Person:
    name: str
    age: int

Additionally, the weakref_slot parameter, when set to True, allows instances of your class to be weakly referenced. This is useful in certain memory management scenarios.

@dataclass(weakref_slot=True)
class Person:
    name: str
    age: int

Well, these are a lot of parameters as you can see, so let’s go ahead and combine some of them into one example to make things even clearer. Let’s say we want to create a class to represent a Student with attributes like name, grade, and student_id. We'll use the frozen, order, and unsafe_hash parameters to demonstrate their utility.

from dataclasses import dataclass

@dataclass(frozen=True, order=True, unsafe_hash=True)
class Student:
    name: str
    grade: float
    student_id: int

# Creating instances
student1 = Student("Alice", 90.5, 101)
student2 = Student("Bob", 85.0, 102)
student3 = Student("Charlie", 92.0, 103)

# Trying to modify an instance (will raise an error)
# student1.grade = 95.0  # Uncommenting this line will raise an error

# Comparing instances
print(student1 < student2)  # Output: False
print(student1 > student2)  # Output: True

# Using instances in a set
students_set = {student1, student2, student3}
print(students_set)
# Output: {Student(name='Alice', grade=90.5, student_id=101), Student(name='Bob', grade=85.0, student_id=102), Student(name='Charlie', grade=92.0, student_id=103)}

So, as you may notice, setting the frozen parameter to True makes the Student class immutable. Once an instance is created, its attributes cannot be changed. This is useful for creating read-only data structures and ensuring data integrity.

Get achraf’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Setting order to True generates comparison methods (__lt__, __le__, __gt__, __ge__), allowing us to compare and sort Student instances based on their attributes. This is useful for ordering and sorting.

Setting the unsafe_hash parameter to True generates a __hash__() method, allowing instances of the Student class to be used in hash-based collections like sets and dictionaries. This is useful for ensuring that instances can be used as keys in dictionaries or stored in sets.

Using these parameters together, in the previous example, showcases the power and importance of dataclasses. They help ensure data integrity with immutability, provide useful functionality for comparison and sorting, and allow instances to be used in hash-based collections. This makes your code more robust, maintainable, and versatile.

Nice, that is a lot of features provided by dataclasses, but that’s not all — there is more to know about the features that dataclasses provide. So let’s see what’s next. Before doing that, we need to know the difference between mutable data types and immutable data types if you don’t already know. Let’s do it.

Mutable Data Types

As the name implies, mutable data types are objects whose state or content can be changed after they are created. This simply means that when you modify a mutable object, the changes are reflected in all references to that object. Examples include lists, dictionaries, and sets.

"""Lists""" 
my_list = [1, 2, 3]
my_list.append(4)  # my_list is now [1, 2, 3, 4]

# Dictionaries
my_dict = {'a': 1, 'b': 2}
my_dict['c'] = 3  # my_dict is now {'a': 1, 'b': 2, 'c': 3}

# Sets
my_set = {1, 2, 3}
my_set.add(4)  # my_set is now {1, 2, 3, 4}

Immutable Data Types

On the other hand, immutable data types are objects whose state or content cannot be changed after they are created. This means when you modify an immutable object, a new object is created, and the original object remains unchanged. Examples include strings, ints, floats, tuples, and frozensets.

"""Strings"""
my_string = "hello"
my_string = my_string + " world"  # my_string is now "hello world", but the original "hello" string is unchanged

# Tuples
my_tuple = (1, 2, 3)
# You can't do something like my_tuple.append(4), this would raise an AttributeError

# ints and floats 
x = 5
x += 1  # x is now 6, but this creates a new int and binds x to it

Why It Matters

So, as you may notice, the difference between mutable and immutable datatypes is all about whether or not you can change the content of the datatype after it’s been created. Nice, but you might ask why we need to know the difference between them and their relation to dataclasses. Well, to discover that, let’s say you’re building a class, but you want to ensure each instance has its own separate mutable attributes, like lists or dictionaries. In regular Python classes and dataclasses, setting default values for mutable types can lead to all instances sharing the same mutable object, which can cause unexpected bugs and issues. To understand this more, let’s see the following example:

from dataclasses import dataclass

@dataclass
class Person:
    name: str
    hobbies: list = []  # Shared list!

# Creating instances
person1 = Person("Alice")
person2 = Person("Bob")

# Modifying the hobbies list of person1
person1.hobbies.append("Reading")

print(person1.hobbies)  # Output: ['Reading']
print(person2.hobbies)  # Output: ['Reading'] - This is unexpected!

In this example, both person1 and person2 share the same hobbies list. Modifying the list for one instance affects the other instance as well. This happens because the list is created once and shared among all instances.

Note that this unexpected behavior occurs not only in dataclasses but also in regular Python classes. This issue arises when using mutable data types, such as lists or dictionaries, which can be altered in place. In contrast, immutable data types do not exhibit this behavior since their values cannot be changed after they are created as shown in the following code:

@dataclass
class Person:
    name: str
    age: int = 25

# Creating instances
person1 = Person("Alice")
person2 = Person("Bob")

# Changing the age for person1
person1.age = 30
print(person1.age)  # Output: 30
print(person2.age)  # Output: 25

In this example, age is an immutable type (int). Changing the age for person1 does not affect person2 because numbers (ints) are immutable, and each instance gets its own copy of the value.

So, now that we know that, we need to find a solution to avoid the issue of shared mutable default values. This is where the field function from the dataclasses module comes to the rescue.

The field function is part of Python's dataclasses module. It provides additional control over how individual fields in a dataclass are handled, which means it allows you to customize the behavior of individual fields in a dataclass. It is especially useful for specifying default values for mutable types, handling metadata, and controlling initialization behavior.

It allows you to specify default values for fields in your dataclasses as you can see in this example:

from dataclasses import dataclass, field

@dataclass
class Person:
    name: str
    age: int = field(default=25)

person = Person("Bob")
print(person)  # Output: Person(name='Bob', age=25)

It also allows the use of Default Values for Mutable Types. Using field(default_factory=...), you can ensure that each instance of your dataclass gets its own separate default value. To understand that more clearly, let’s fix the problem of our previous example using the field function to ensure each instance gets its own list:

from dataclasses import dataclass, field

@dataclass
class Person:
    name: str
    hobbies: list = field(default_factory=list)  # Each instance gets a separate list

# Creating instances
person1 = Person("Alice")
person2 = Person("Bob")

# Modifying the hobbies list of person1
person1.hobbies.append("Reading")

print(person1.hobbies)  # Output: ['Reading']
print(person2.hobbies)  # Output: [] - Separate lists!, This is expected!

In this example, each instance of Person gets its own separate hobbies list, so modifying one instance does not affect the other.

You can also attach metadata to a field, which can be useful for various purposes, such as validation or documentation.

@dataclass
class Person:
    name: str
    age: int = field(default=25, metadata={"unit": "years"})

person = Person("Charlie")
print(person)  # Output: Person(name='Charlie', age=25)
print(person.__dataclass_fields__['age'].metadata)  # Output: {'unit': 'years'}

Additionally, you can exclude fields from certain generated methods like __repr__ or __eq__ as shown in the example below:

@dataclass
class Person:
    name: str
    age: int = field(default=25, repr=False)

person = Person("Diana")
print(person)  # Output: Person(name='Diana')

Nice, right? You can get all of these really cool features by just using dataclasses. But that’s not all, so let’s go ahead and discover the following dataclasses features.

As you know, dataclasses, while powerful, are still Python classes. They support inheritance just like regular classes and work much the same way. This allows you to create a new dataclass that inherits attributes and methods from a parent dataclass. It’s useful for creating a hierarchy of classes with shared functionality, reducing code duplication, and promoting a cleaner, more organized codebase.

from dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: int

@dataclass
class Employee(Person):
    employee_id: int
    department: str

emp = Employee(name="Alice", age=30, employee_id=1234, department="Engineering")
print(emp)

In this example, Employee inherits from Person, adding its own additional fields while retaining the fields from Person.

Nice, right? You can see now how dataclasses are powerful and the cool features they provide. But there is still another feature we need to know about: post-initialization processing. This feature allows you to perform additional actions after the dataclass is initialized. This is done using the __post_init__ method, which is automatically called after the __init__ method. It’s especially useful for any validation or additional setup that needs to be done with the initial field values. Here’s an example:

from dataclasses import dataclass

@dataclass
class Product:
    name: str
    price: float
    discount: float

    def __post_init__(self):
        if self.discount > self.price, it will raise a ValueError.:
            raise ValueError("Discount cannot be greater than the price.")

try:
    p = Product(name="Laptop", price=1000.0, discount=1200.0)
except ValueError as e:
    print(e)  # Output: Discount cannot be greater than the price.

In this example, the __post_init__ method checks if the discount is greater than the price and raises an error if it is, ensuring that invalid states are prevented.

In essence, dataclasses in Python are a powerful tool for simplifying code, ensuring clarity, and providing robust solutions for managing data. With features like automatic method generation, type annotations, and the versatile field function, they transform how we handle class attributes, especially mutables. Inheritance and post-initialization further enhance their utility, making your code cleaner and more maintainable.