I. Python `dataclasses` — Complete Learning Handbook#

Overview: Python's dataclasses module (introduced in Python 3.7) provides a decorator (装饰器) that automatically generates boilerplate methods — __init__, __repr__, __eq__ — for classes that primarily store data. It sits between a plain class and a full ORM/validation framework, offering clean syntax with zero runtime overhead beyond standard Python.

1. Installation & Import#

dataclasses is part of the Python standard library — no installation required.

1
from dataclasses import dataclass, field, fields, asdict, astuple, replace, KW_ONLY

2. Defining a Dataclass (定义数据类)#

1) Basic Definition#

1
from dataclasses import dataclass
2

3
@dataclass
4
class Point:
5
    x: float
6
    y: float
7

8
p = Point(x=1.0, y=2.0)
9
print(p)          # Point(x=1.0, y=2.0)
10
print(p.x)        # 1.0
11
print(p == Point(1.0, 2.0))   # True

The @dataclass decorator auto-generates:

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

2) Fields with Default Values (默认值)#

1
@dataclass
2
class User:
3
    name: str
4
    age: int = 0
5
    active: bool = True
6

7
u = User(name="Alice")
8
print(u)   # User(name='Alice', age=0, active=True)

Note: Fields with defaults must come after fields without defaults — same rule as regular Python function parameters. Violating this raises a TypeError.

3) `field()` — Advanced Field Configuration#

1
from dataclasses import dataclass, field
2

3
@dataclass
4
class Config:
5
    tags: list[str] = field(default_factory=list)     # Mutable default
6
    name: str = field(default="unnamed")
7
    _secret: str = field(default="", repr=False)       # Hidden from repr
8
    metadata: dict = field(default_factory=dict, compare=False)  # Excluded from ==

`field()` Parameter Reference#

Parameter	Default	Effect
`default`	`MISSING`	Scalar default value
`default_factory`	`MISSING`	Callable that produces the default (for mutable types)
`repr`	`True`	Include field in `__repr__` output
`compare`	`True`	Include field in `__eq__` and `__lt__` etc.
`hash`	`None`	Include field in `__hash__` (None = follow `compare`)
`init`	`True`	Include field as a parameter in `__init__`
`metadata`	`None`	Arbitrary read-only mapping attached to the field
`kw_only`	`False`	Force this field to be keyword-only in `__init__` (3.10+)

Note: Never use a mutable object (list, dict, set) directly as a default value. Use field(default_factory=list) — otherwise all instances share the same object.

4) Nested Dataclasses (嵌套数据类)#

1
@dataclass
2
class Address:
3
    city: str
4
    country: str
5

6
@dataclass
7
class Person:
8
    name: str
9
    address: Address
10

11
p = Person(name="Bob", address=Address(city="NYC", country="US"))
12
print(p.address.city)   # NYC
13
print(p)
14
# Person(name='Bob', address=Address(city='NYC', country='US'))

3. `@dataclass` Decorator Options (装饰器配置)#

1
@dataclass(frozen=True, order=True, eq=True, repr=True, unsafe_hash=False, slots=True)
2
class Config:
3
    x: int
4
    y: int

Option Reference Table#

Option	Default	Effect
`init`	`True`	Generate `__init__`
`repr`	`True`	Generate `__repr__`
`eq`	`True`	Generate `__eq__` based on field values
`order`	`False`	Generate `__lt__`, `__le__`, `__gt__`, `__ge__`
`frozen`	`False`	Make instances immutable (不可变) — raises `FrozenInstanceError` on assignment
`unsafe_hash`	`False`	Force generate `__hash__` even if `eq=True` (use with care)
`slots`	`False`	Use `__slots__` for faster attribute access and lower memory (3.10+)
`kw_only`	`False`	All fields must be passed as keyword arguments (3.10+)
`match_args`	`True`	Generate `__match_args__` for structural pattern matching (3.10+)

1) `frozen=True` — Immutable Dataclass#

1
@dataclass(frozen=True)
2
class ImmutablePoint:
3
    x: float
4
    y: float
5

6
p = ImmutablePoint(x=1.0, y=2.0)
7
p.x = 99.0   # ❌ FrozenInstanceError: cannot assign to field 'x'
8

9
# Frozen dataclasses are hashable and can be used as dict keys
10
d = {p: "origin"}

Scenario: Configuration objects (配置对象), cache keys, value objects (值对象) that must never be mutated.

2) `order=True` — Sortable Dataclasses#

1
@dataclass(order=True)
2
class Version:
3
    major: int
4
    minor: int
5
    patch: int
6

7
versions = [Version(1, 2, 0), Version(1, 0, 5), Version(2, 0, 0)]
8
print(sorted(versions))
9
# [Version(major=1, minor=0, patch=5), Version(major=1, minor=2, patch=0), Version(major=2, minor=0, patch=0)]

Scenario: Sorting records, priority queues, range-based comparisons.

3) `slots=True` — Memory-efficient Dataclass (Python 3.10+)#

1
@dataclass(slots=True)
2
class FastPoint:
3
    x: float
4
    y: float
5

6
# __slots__ prevents arbitrary attribute addition and speeds up attribute access
7
p = FastPoint(1.0, 2.0)
8
p.z = 3.0   # ❌ AttributeError: 'FastPoint' object has no attribute 'z'

Scenario: Creating millions of small instances (数百万小对象) — data pipelines, geometry, particle simulations.

4) `kw_only=True` — Keyword-only Fields (Python 3.10+)#

1
@dataclass(kw_only=True)
2
class Request:
3
    url: str
4
    method: str = "GET"
5
    timeout: float = 30.0
6

7
r = Request(url="https://api.example.com")
8
# r = Request("https://api.example.com")  ❌ TypeError

Use KW_ONLY sentinel to make only some fields keyword-only:

1
from dataclasses import KW_ONLY
2

3
@dataclass
4
class Mixed:
5
    x: int
6
    y: int
7
    _: KW_ONLY          # Everything after this is keyword-only
8
    label: str = ""
9
    weight: float = 1.0
10

11
m = Mixed(1, 2, label="point")   # x and y are positional, label is kw-only

4. `__post_init__` — Post-initialization Hook (初始化后钩子)#

Runs automatically after __init__ completes. Use it for validation, derived fields, or type coercion.

1) Validation#

1
@dataclass
2
class Temperature:
3
    celsius: float
4

5
    def __post_init__(self):
6
        if self.celsius < -273.15:
7
            raise ValueError(f"Temperature {self.celsius}°C is below absolute zero!")
8

9
t = Temperature(-300)   # ❌ ValueError

2) Derived Fields with `field(init=False)`#

1
import math
2

3
@dataclass
4
class Circle:
5
    radius: float
6
    area: float = field(init=False)        # Not in __init__
7
    circumference: float = field(init=False)
8

9
    def __post_init__(self):
10
        self.area = math.pi * self.radius ** 2
11
        self.circumference = 2 * math.pi * self.radius
12

13
c = Circle(radius=5.0)
14
print(c.area)           # 78.539...
15
print(c.circumference)  # 31.415...

3) Type Coercion#

1
@dataclass
2
class Coordinate:
3
    lat: float
4
    lon: float
5

6
    def __post_init__(self):
7
        # Auto-convert strings to float
8
        self.lat = float(self.lat)
9
        self.lon = float(self.lon)
10

11
coord = Coordinate(lat="51.5", lon="-0.1")
12
print(coord.lat, type(coord.lat))   # 51.5 <class 'float'>

4) `InitVar` — Init-only Parameters (仅初始化参数)#

Fields that exist in __init__ but are NOT stored as instance attributes:

1
from dataclasses import dataclass, field, InitVar
2

3
@dataclass
4
class HashedPassword:
5
    username: str
6
    raw_password: InitVar[str]           # Passed to __init__ but not stored
7
    password_hash: str = field(init=False)
8

9
    def __post_init__(self, raw_password: str):
10
        import hashlib
11
        self.password_hash = hashlib.sha256(raw_password.encode()).hexdigest()
12

13
u = HashedPassword(username="alice", raw_password="secret123")
14
print(u.password_hash)    # sha256 hash
15
# print(u.raw_password)   # ❌ AttributeError — not stored

5. Utility Functions (工具函数)#

1) `asdict()` — Convert to Dictionary#

1
from dataclasses import asdict
2

3
@dataclass
4
class Point:
5
    x: float
6
    y: float
7

8
p = Point(1.0, 2.0)
9
print(asdict(p))   # {'x': 1.0, 'y': 2.0}

Works recursively on nested dataclasses:

1
person = Person(name="Bob", address=Address(city="NYC", country="US"))
2
print(asdict(person))
3
# {'name': 'Bob', 'address': {'city': 'NYC', 'country': 'US'}}

2) `astuple()` — Convert to Tuple#

1
from dataclasses import astuple
2

3
print(astuple(p))   # (1.0, 2.0)

3) `replace()` — Copy with Changes (不可变更新)#

Creates a new instance with specified fields replaced — the original is unchanged:

1
from dataclasses import replace
2

3
p = Point(x=1.0, y=2.0)
4
p2 = replace(p, x=99.0)
5
print(p2)   # Point(x=99.0, y=2.0)
6
print(p)    # Point(x=1.0, y=2.0)  ← original unchanged

Scenario: Immutable update patterns — building modified configurations, functional state updates.

4) `fields()` — Inspect Field Definitions#

1
from dataclasses import fields
2

3
for f in fields(Point):
4
    print(f.name, f.type, f.default)
5
# x  float  MISSING
6
# y  float  MISSING

Scenario: Writing generic serializers, validators, or introspection utilities (内省工具).

5) `is_dataclass()` — Runtime Type Check#

1
from dataclasses import is_dataclass
2

3
print(is_dataclass(Point))      # True  (class)
4
print(is_dataclass(Point(1,2))) # True  (instance)
5
print(is_dataclass(int))        # False

6. Inheritance (继承)#

1
@dataclass
2
class Animal:
3
    name: str
4
    age: int
5

6
@dataclass
7
class Dog(Animal):
8
    breed: str
9
    trained: bool = False
10

11
d = Dog(name="Rex", age=3, breed="Husky")
12
print(d)   # Dog(name='Rex', age=3, breed='Husky', trained=False)

Note: If a parent class has a field with a default value, the child class cannot add fields without a default — this violates the "defaults must come last" rule and raises a TypeError. Use kw_only=True on the child to avoid this.

1
@dataclass
2
class Base:
3
    x: int = 0     # Has default
4

5
@dataclass(kw_only=True)
6
class Child(Base):
7
    y: int         # No default — OK because kw_only avoids ordering conflict

7. Hashing & Usage as Dict Keys (哈希与字典键)#

1
# eq=True + frozen=True → hashable
2
@dataclass(frozen=True)
3
class Point:
4
    x: float
5
    y: float
6

7
p = Point(1.0, 2.0)
8
cache = {p: "result"}   # ✅ Can be used as dict key or in set
9

10
# eq=True + frozen=False (default) → NOT hashable
11
@dataclass
12
class MutablePoint:
13
    x: float
14
    y: float
15

16
mp = MutablePoint(1.0, 2.0)
17
# {mp: "x"}  ❌ TypeError: unhashable type

`eq`	`frozen`	`__hash__`
`False`	`False`	Inherited from `object` (id-based)
`True`	`False`	Set to `None` — unhashable
`True`	`True`	Generated — hashable ✅
`True`	`False` + `unsafe_hash=True`	Force-generated — use with caution

8. Pattern Matching with Dataclasses (Python 3.10+)#

1
@dataclass
2
class Point:
3
    x: float
4
    y: float
5

6
def describe(p):
7
    match p:
8
        case Point(x=0, y=0):
9
            return "Origin"
10
        case Point(x=0, y=y):
11
            return f"On Y-axis at {y}"
12
        case Point(x=x, y=0):
13
            return f"On X-axis at {x}"
14
        case Point(x=x, y=y):
15
            return f"Point at ({x}, {y})"
16

17
print(describe(Point(0, 5)))     # On Y-axis at 5
18
print(describe(Point(3, 4)))     # Point at (3, 4)

9. Comparison: `dataclasses` vs Alternatives#

Feature	`dataclasses`	`attrs`	`msgspec.Struct`	`pydantic`
Stdlib	✅ Yes	❌	❌	❌
Auto `__init__`	✅	✅	✅	✅
Validation	❌ Manual	✅ (validators)	✅ Built-in	✅ Built-in
Serialization	❌ Manual	❌ Manual	✅ JSON/MsgPack	✅ JSON
Performance	⚡ Fast	⚡ Fast	⚡⚡ Fastest	🐢→⚡ (v1→v2)
Frozen support	✅	✅	✅	✅
`__slots__`	✅ (3.10+)	✅	✅ (C-level)	❌
Inheritance	✅	✅	✅ (limited)	✅
Ecosystem fit	Standard Python	Power users	High-perf I/O	Web APIs

10. Real-World Scenarios (实战场景)#

1) Configuration Object#

1
from dataclasses import dataclass, field
2

3
@dataclass(frozen=True)
4
class AppConfig:
5
    host: str = "0.0.0.0"
6
    port: int = 8080
7
    debug: bool = False
8
    allowed_origins: tuple[str, ...] = ("*",)
9

10
config = AppConfig(port=9000, debug=True)
11
print(config)
12
# AppConfig(host='0.0.0.0', port=9000, debug=True, allowed_origins=('*',))

2) Data Pipeline Record#

1
from dataclasses import dataclass, field
2
from datetime import datetime
3

4
@dataclass(slots=True)
5
class LogRecord:
6
    timestamp: datetime
7
    level: str
8
    message: str
9
    tags: list[str] = field(default_factory=list)
10

11
records = [LogRecord(datetime.now(), "INFO", f"event {i}") for i in range(1_000_000)]

3) API Request / Response Model#

1
import json
2
from dataclasses import dataclass, asdict, field
3
from typing import Optional
4

5
@dataclass
6
class CreateUserRequest:
7
    username: str
8
    email: str
9
    age: Optional[int] = None
10

11
@dataclass
12
class UserResponse:
13
    id: int
14
    username: str
15
    email: str
16

17
req = CreateUserRequest(username="alice", email="alice@example.com")
18
resp = UserResponse(id=42, username=req.username, email=req.email)
19
print(json.dumps(asdict(resp)))
20
# {"id": 42, "username": "alice", "email": "alice@example.com"}

4) State Machine Node#

1
from dataclasses import dataclass, replace
2
from typing import Literal
3

4
@dataclass(frozen=True)
5
class JobState:
6
    job_id: str
7
    status: Literal["pending", "running", "done", "failed"]
8
    retries: int = 0
9

10
# Immutable state transitions
11
initial = JobState(job_id="abc", status="pending")
12
running = replace(initial, status="running")
13
failed  = replace(running, status="failed", retries=running.retries + 1)
14
retry   = replace(failed,  status="running", retries=failed.retries)
15

16
print(initial)   # JobState(job_id='abc', status='pending', retries=0)
17
print(retry)     # JobState(job_id='abc', status='running', retries=1)

💡 One-line Takeaway
Use @dataclass as your default data container, frozen=True for immutable value objects and hashable keys, __post_init__ for validation and derived fields, replace() for functional state updates, and slots=True when creating millions of instances.

I. Python dataclasses — Complete Learning Handbook#

1. Installation & Import#

2. Defining a Dataclass (定义数据类)#

1) Basic Definition#

2) Fields with Default Values (默认值)#

3) field() — Advanced Field Configuration#

field() Parameter Reference#

4) Nested Dataclasses (嵌套数据类)#

3. @dataclass Decorator Options (装饰器配置)#

Option Reference Table#

1) frozen=True — Immutable Dataclass#

2) order=True — Sortable Dataclasses#

3) slots=True — Memory-efficient Dataclass (Python 3.10+)#

4) kw_only=True — Keyword-only Fields (Python 3.10+)#

4. __post_init__ — Post-initialization Hook (初始化后钩子)#