I. Dataclass#

Python dataclass is a decorator (装饰器) that automatically generates special methods like __init__ and __repr__ for classes primarily used to store data. It reduces boilerplate code by letting you declare fields as class variables with type annotations. The dataclass makes your code more readable and maintainable (可读性和可维护性) by eliminating repetitive method definitions.

1. Basic Dataclass Definition#

The @dataclass decorator (装饰器) automatically adds __init__, __repr__, and __eq__ methods based on the class variables you define with type hints (类型提示). Use this when you need a simple container for data without writing repetitive constructor code.

The `@dataclass` decorator auto-generates:

init(self, x, y) — constructor
repr — pretty string representation
eq — equality comparison

1) Basic Implementation#

1
from dataclasses import dataclass
2

3
@dataclass
4
class Person:
5
    name: str
6
    age: int
7
    email: str = "unknown@email.com"  # Default value
8

9
# Usage example
10
person1 = Person("Alice", 25, "alice@email.com")
11
person2 = Person("Bob", 30)  # Uses default email
12

13
print(person1)  # Automatically generated __repr__
14
print(person1 == person2)  # Automatically generated __eq__

Note: Fields without default values must come before fields with default values, otherwise Python raises a SyntaxError (语法错误).

2. Field Customization#

The field() function (字段函数) provides fine-grained control over individual dataclass fields, allowing you to set default factories (默认工厂), exclude fields from comparisons, or mark fields as private (私有).

1) Using field() with Parameters#

1
from dataclasses import dataclass, field
2
import random
3
from typing import List
4

5
@dataclass
6
class Student:
7
    name: str
8
    student_id: int = field(init=False)  # Not in __init__
9
    grades: List[int] = field(default_factory=list)  # Mutable default
10
    _internal_id: int = field(default=0, repr=False)  # Hidden in __repr__
11

12
    def __post_init__(self):
13
        # Initialize after dataclass generation
14
        self.student_id = random.randint(1000, 9999)
15
        self._internal_id = hash(self.name)
16

17
# Usage example
18
student = Student("Alice")
19
student.grades.append(95)  # Works with mutable default
20
print(student)  # Shows name and grades, but not _internal_id

Note: Always use default_factory (默认工厂) for mutable types like lists or dictionaries. Using grades: List[int] = [] would cause all instances to share the same list.

3. Dataclass Parameters#

The @dataclass decorator accepts parameters that control which methods are generated. Use frozen=True for immutable objects, order=True for sorting capabilities, and kw_only=True to enforce keyword arguments.

1) Configuration Options#

1
from dataclasses import dataclass
2

3
@dataclass(frozen=True, order=True)
4
class Point:
5
    x: int
6
    y: int
7

8
@dataclass(kw_only=True)  # Python 3.10+
9
class Configuration:
10
    host: str
11
    port: int = 8080
12

13
# Usage examples
14
p1 = Point(1, 2)
15
p2 = Point(1, 3)
16
# p1.x = 5  # This would raise FrozenInstanceError
17
print(p1 < p2)  # Works because order=True
18

19
# Must use keyword arguments
20
config = Configuration(host="localhost", port=3000)
21
# config = Configuration("localhost", 3000)  # This would fail

Note: When using frozen=True, the dataclass becomes immutable (不可变的) — you cannot modify attributes after creation. This is ideal for configuration objects or value objects.

4. Inheritance with Dataclasses#

Dataclasses support inheritance (继承), with fields from parent classes being combined with child class fields. Use this when you need to extend data containers while maintaining the automatic method generation.

1) Extending Dataclasses#

1
from dataclasses import dataclass
2

3
@dataclass
4
class Vehicle:
5
    brand: str
6
    model: str
7
    year: int
8

9
@dataclass
10
class Car(Vehicle):
11
    doors: int
12
    electric: bool = False
13

14
# Usage example
15
my_car = Car("Tesla", "Model 3", 2023, doors=4, electric=True)
16
print(my_car)  # Includes all fields from both classes

Note: When inheriting, the field order matters — child class fields are appended after parent fields. All fields without defaults in the parent must come before child fields with defaults.

5. Comparison Table: Regular Class vs Dataclass#

This table compares the boilerplate code (样板代码) required for a simple data container using a regular class versus a dataclass.

Feature	Regular Class	Dataclass
Lines of Code	~10-15 lines	~3-5 lines
init method	Manual implementation	Auto-generated
repr method	Manual implementation	Auto-generated
eq method	Manual implementation	Auto-generated
Type hints	Optional in body	Required for fields
Default values	In init method	Direct field assignment
Mutable defaults	Safe with proper code	Must use default_factory

1) Code Comparison Example#

1
# Regular class - 15 lines
2
class RegularPerson:
3
    def __init__(self, name: str, age: int, email: str = "unknown"):
4
        self.name = name
5
        self.age = age
6
        self.email = email
7

8
    def __repr__(self):
9
        return f"RegularPerson(name='{self.name}', age={self.age}, email='{self.email}')"
10

11
    def __eq__(self, other):
12
        if not isinstance(other, RegularPerson):
13
            return False
14
        return (self.name, self.age, self.email) == (other.name, other.age, other.email)
15

16
# Dataclass - 4 lines
17
@dataclass
18
class DataclassPerson:
19
    name: str
20
    age: int
21
    email: str = "unknown"

💡 One-line Takeaway
Python dataclasses automatically generate __init__, __repr__, and __eq__ from type-annotated fields, eliminating boilerplate code for simple data containers.