{"id":2943,"date":"2021-11-15T11:53:37","date_gmt":"2021-11-15T11:53:37","guid":{"rendered":"https:\/\/www.pythontutorial.net\/?page_id=2943"},"modified":"2021-11-15T11:57:32","modified_gmt":"2021-11-15T11:57:32","slug":"python-dataclass","status":"publish","type":"page","link":"https:\/\/www.pythontutorial.net\/python-oop\/python-dataclass\/","title":{"rendered":"Python dataclass"},"content":{"rendered":"\n

Summary<\/strong>: in this tutorial, you’ll learn about the Python dataclass decorator and how to use it effectively.<\/p>\n\n\n\n

Introduction to the Python dataclass #<\/a><\/h2>\n\n\n\n

Python introduced the dataclass in version 3.7 (PEP 557<\/a>). The dataclass allows you to define classes<\/a> with less code and more functionality out of the box.<\/p>\n\n\n\n

The following defines a regular Person<\/code> class with two instance attributes name<\/code> and age<\/code>:<\/p>\n\n\n

class<\/span> Person<\/span>:<\/span>\n    def<\/span> __init__<\/span>(self, name, age)<\/span>:<\/span>\n        self.name = name\n        self.age = age\n<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
This Person<\/code> class has the __init__<\/code> method that initializes the name<\/code> and age<\/code> attributes. <\/p>\n\n\n\n
However, if you use the dataclass, you’ll have all of these features (and even more) without implementing these dunder methods.<\/p>\n\n\n\n
To make the Person<\/code> class a data class, you follow these steps:<\/p>\n\n\n\n
First, import the dataclass<\/code> decorator from the dataclasses<\/code> module:<\/p>\n\n\n
from<\/span> dataclasses import<\/span> dataclass<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Second, decorate the Person<\/code> class with the dataclass<\/code> decorator and declare the attributes:<\/p>\n\n\n
@dataclass<\/span>\nclass<\/span> Person<\/span>:<\/span>\n    name: str\n    age: int<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
In this example, the Person<\/code> class has two attributes name<\/code> with the type str<\/code> and age<\/code> with the type int<\/code>. By doing this, the @dataclass decorator implicitly creates the __init__<\/code> method like this:<\/p>\n\n\n
def<\/span> __init__<\/span>(name: str, age: int)<\/span><\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Note that the order of the attributes declared in the class will determine the orders of the parameters in the __init__<\/code> method.<\/p>\n\n\n\n
And you can create the Person<\/code>‘s object:<\/p>\n\n\n
p1 = Person('John'<\/span>, 25<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
When printing out the Person<\/code>‘s object, you’ll get a readable format:<\/p>\n\n\n
print(p1)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Person(name='John'<\/span>, age=25<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Also, if you compare two Person<\/code>‘s objects with the same attribute value, it’ll return True<\/code>. For example:<\/p>\n\n\n
p1 = Person('John'<\/span>, 25<\/span>)\np2 = Person('John'<\/span>, 25<\/span>)\nprint(p1 == p2)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
True<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The following discusses other functions that a data class provides.<\/p>\n\n\n\n
Default values #<\/a><\/h2>\n\n\n\n
When using a regular class, you can define default values for attributes. For example, the following Person<\/code> class has the iq<\/code> parameter with the default value of 100<\/code>.<\/p>\n\n\n
class<\/span> Person<\/span>:<\/span>\n    def<\/span> __init__<\/span>(self, name, age, iq=100<\/span>)<\/span>:<\/span>\n        self.name = name\n        self.age = age\n        self.iq = iq<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
To define a default value for an attribute in the dataclass, you assign it to the attribute like this:<\/p>\n\n\n
from<\/span> dataclasses import<\/span> dataclass\n\n\n@dataclass<\/span>\nclass<\/span> Person<\/span>:<\/span>\n    name: str\n    age: int\n    iq: int = 100<\/span>\n\n\nprint(Person('John Doe'<\/span>, 25<\/span>))<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Like the parameter rules, the attributes with the default values must appear after the ones without default values. Therefore, the following code will not work:<\/p>\n\n\n
from<\/span> dataclasses import<\/span> dataclass\n\n\n@dataclass<\/span>\nclass<\/span> Person<\/span>:<\/span>\n    iq: int = 100<\/span>\n    name: str\n    age: int<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Convert to a tuple or a dictionary #<\/a><\/h2>\n\n\n\n
The dataclasses<\/code> module has the astuple()<\/code> and asdict()<\/code> functions that convert an instance of the dataclass to a tuple<\/a> and a dictionary<\/a>. For example:<\/p>\n\n\n
from<\/span> dataclasses import<\/span> dataclass, astuple, asdict\n\n\n@dataclass<\/span>\nclass<\/span> Person<\/span>:<\/span>\n    name: str\n    age: int\n    iq: int = 100<\/span>\n\n\np = Person('John Doe'<\/span>, 25<\/span>)\n\nprint(astuple(p))\nprint(asdict(p))<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
('John Doe'<\/span>, 25<\/span>, 100<\/span>)\n{'name'<\/span>: 'John Doe'<\/span>, 'age'<\/span>: 25<\/span>, 'iq'<\/span>: 100<\/span>}<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Create immutable objects #<\/a><\/h2>\n\n\n\n
To create readonly objects from a dataclass, you can set the frozen argument of the dataclass decorator to True<\/code>. For example:<\/p>\n\n\n
from<\/span> dataclasses import<\/span> dataclass, astuple, asdict\n\n\n@dataclass(frozen=True)<\/span>\nclass<\/span> Person<\/span>:<\/span>\n    name: str\n    age: int\n    iq: int = 100<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
If you attempt to change the attributes of the object after it is created, you’ll get an error. For example:<\/p>\n\n\n
p = Person('Jane Doe'<\/span>, 25<\/span>)\np.iq = 120<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Error:<\/p>\n\n\n
dataclasses.FrozenInstanceError: cannot assign to field 'iq'<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Customize attribute behaviors #<\/a><\/h2>\n\n\n\n
If don’t want to initialize an attribute in the __init__ method, you can use the field()<\/code> function from the dataclasses<\/code> module.<\/p>\n\n\n\n
The following example defines the can_vote<\/code> attribute that is initialized using the __init__<\/code> method:<\/p>\n\n\n
from<\/span> dataclasses import<\/span> dataclass, field\n\n\nclass<\/span> Person<\/span>:<\/span>\n    name: str\n    age: int\n    iq: int = 100<\/span>\n    can_vote: bool = field(init=False<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The field()<\/code> function has multiple interesting parameters such as repr<\/code>, hash<\/code>, compare<\/code>, and metadata<\/code>.<\/p>\n\n\n\n
If you want to initialize an attribute that depends on the value of another attribute, you can use the __post_init__<\/code> method. As its name implies, Python calls the __post_init__<\/code> method after the __init__<\/code> method. <\/p>\n\n\n\n
The following use the __post_init__<\/code> method to initialize the can_vote<\/code> attribute based on the age<\/code> attribute:<\/p>\n\n\n
from<\/span> dataclasses import<\/span> dataclass, field\n\n\n@dataclass<\/span>\nclass<\/span> Person<\/span>:<\/span>\n    name: str\n    age: int\n    iq: int = 100<\/span>\n    can_vote: bool = field(init=False<\/span>)\n\n    def<\/span> __post_init__<\/span>(self)<\/span>:<\/span>\n        print('called __post_init__ method'<\/span>)\n        self.can_vote = 18<\/span> <= self.age <= 70<\/span>\n\n\np = Person('Jane Doe'<\/span>, 25<\/span>)\nprint(p)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
called the __post_init__ method\nPerson(name='Jane Doe'<\/span>, age=25<\/span>, iq=100<\/span>, can_vote=True<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Sort objects #<\/a><\/h2>\n\n\n\n
By default, a dataclass implements the __eq__<\/code> method.<\/p>\n\n\n\n
To allow different types of comparisons like __lt__<\/code>, __lte__<\/code>, __gt__<\/code>, __gte__<\/code>, you can set the order argument of the @dataclass<\/code> decorator to True:<\/p>\n\n\n
@dataclass<\/span>(order=True)<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
By doing this, the dataclass will sort the objects by every field until it finds a value that’s not equal. <\/p>\n\n\n\n
In practice, you often want to compare objects by a particular attribute, not all attributes. To do that, you need to define a field called sort_index<\/code> and set its value to the attribute that you want to sort.<\/p>\n\n\n\n
For example, suppose you have a list of Person<\/code>‘s objects and want to sort them by age:<\/p>\n\n\n
members = [\n    Person('John'<\/span>, 25<\/span>),\n    Person('Bob'<\/span>, 35<\/span>),\n    Person('Alice'<\/span>, 30<\/span>)\n]<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
To do that, you need to:<\/p>\n\n\n\n
If you want to have a string representation of the Person<\/code> object, you need to implement the __str__<\/a><\/code> or __repr__<\/a><\/code> method. Also, if you want to compare two instances of the Person<\/code> class by an attribute, you need to implement the __eq__<\/code> <\/a>method.<\/p>\n\n\n\n