Dataclasses

Intermediate ~25 min read

Dataclasses (Python 3.7+) eliminate boilerplate code when creating classes that primarily store data. The @dataclass decorator automatically generates __init__, __repr__, __eq__, and other methods from class attributes with type hints. What takes 15+ lines traditionally becomes just 4 lines.

What @dataclass Generates

__init__: Initializer with all fields as parameters
__repr__: String representation showing all field values
__eq__: Equality comparison based on all fields
__hash__: Hash function (if frozen=True or eq=False)
Ordering methods: __lt__, __le__, __gt__, __ge__ (if order=True)

Dataclass Basics

A dataclass is defined by decorating a class with @dataclass and using type annotations for fields. The decorator introspects the annotations and generates the necessary methods automatically.

# Dataclass Basics

print("=== Dataclass Basics ===\n")

from dataclasses import dataclass

# 1. Basic dataclass - no boilerplate needed!
print("1. Basic dataclass:")

@dataclass
class Product:
    name: str
    price: float
    quantity: int = 0  # Default value

# Auto-generated __init__
laptop = Product("Laptop", 999.99, 5)
mouse = Product("Mouse", 29.99)  # Uses default quantity=0

print(f"   {laptop}")
print(f"   {mouse}")
print()

# 2. Comparison with traditional class
print("2. Traditional class (lots of boilerplate):")

class TraditionalProduct:
    def __init__(self, name: str, price: float, quantity: int = 0):
        self.name = name
        self.price = price
        self.quantity = quantity

def __repr__(self):
        return f"TraditionalProduct(name={self.name!r}, price={self.price}, quantity={self.quantity})"

def __eq__(self, other):
        if not isinstance(other, TraditionalProduct):
            return NotImplemented
        return (self.name, self.price, self.quantity) == (other.name, other.price, other.quantity)

trad = TraditionalProduct("Keyboard", 79.99, 10)
print(f"   {trad}")
print("   (Required 15+ lines vs 4 lines with @dataclass)")
print()

# 3. Auto-generated __eq__
print("3. Auto-generated __eq__:")

p1 = Product("Phone", 699.99, 10)
p2 = Product("Phone", 699.99, 10)
p3 = Product("Phone", 699.99, 5)

print(f"   p1 == p2: {p1 == p2}")  # True - same values
print(f"   p1 == p3: {p1 == p3}")  # False - different quantity
print(f"   p1 is p2: {p1 is p2}")  # False - different objects
print()

# 4. Custom methods work normally
print("4. Custom methods in dataclasses:")

@dataclass
class Rectangle:
    width: float
    height: float

def area(self):
        """Custom method - works as expected."""
        return self.width * self.height

def perimeter(self):
        """Another custom method."""
        return 2 * (self.width + self.height)

rect = Rectangle(5.0, 3.0)
print(f"   Rectangle: {rect}")
print(f"   Area: {rect.area()}")
print(f"   Perimeter: {rect.perimeter()}")
print()

# 5. Type hints are required
print("5. Type hints are required (but not enforced at runtime):")

@dataclass
class User:
    name: str
    age: int
    email: str = ""

# Python doesn't enforce types at runtime
user = User("Alice", "thirty", 12345)  # Works! But not recommended
print(f"   User with wrong types: {user}")
print("   Note: Use type checkers like mypy for type enforcement")

Output

Click Run to execute your code

Type Hints Are Required, Not Enforced

Dataclasses require type annotations to identify fields, but Python doesn't enforce types at runtime. Use type checkers like mypy or pyright for static type validation during development.

Dataclass Fields

The field() function provides fine-grained control over individual fields. Use it to set mutable defaults, exclude fields from repr/comparison, or add metadata.

# Dataclass Fields

print("=== Dataclass Fields ===\n")

from dataclasses import dataclass, field
from typing import List

# 1. Default values must come after non-defaults
print("1. Field ordering rules:")

@dataclass
class Person:
    # Required fields first (no defaults)
    name: str
    age: int
    # Optional fields last (with defaults)
    email: str = ""
    active: bool = True

person = Person("Alice", 30)
print(f"   {person}")
print()

# 2. Mutable default values - use field(default_factory=...)
print("2. Mutable defaults with default_factory:")

# WRONG way (causes shared mutable default):
# @dataclass
# class WrongInventory:
#     items: list = []  # This would raise ValueError!

# CORRECT way:
@dataclass
class Inventory:
    name: str
    items: List[str] = field(default_factory=list)  # Each instance gets new list

inv1 = Inventory("Warehouse A")
inv2 = Inventory("Warehouse B")

inv1.items.append("Widget")
inv2.items.append("Gadget")

print(f"   inv1: {inv1}")
print(f"   inv2: {inv2}")
print("   Each instance has its own list!")
print()

# 3. Field options
print("3. Field options:")

@dataclass
class Employee:
    name: str
    employee_id: int
    # Don't include in repr
    password: str = field(repr=False)
    # Don't include in comparisons
    login_count: int = field(default=0, compare=False)
    # Don't include in __init__ (computed field)
    display_name: str = field(init=False)

def __post_init__(self):
        self.display_name = f"{self.name} (ID: {self.employee_id})"

e1 = Employee("Alice", 1001, "secret123")
e2 = Employee("Alice", 1001, "different_pwd")

print(f"   {e1}")  # password hidden in repr
print(f"   Display name: {e1.display_name}")
print(f"   e1 == e2: {e1 == e2}")  # True! password and login_count not compared
print()

# 4. field() with default_factory for complex defaults
print("4. Complex default values:")

from datetime import datetime

@dataclass
class LogEntry:
    message: str
    level: str = "INFO"
    timestamp: datetime = field(default_factory=datetime.now)
    tags: List[str] = field(default_factory=list)
    metadata: dict = field(default_factory=dict)

log1 = LogEntry("Server started")
log2 = LogEntry("Error occurred", level="ERROR", tags=["critical"])

print(f"   Log 1: {log1.message} at {log1.timestamp}")
print(f"   Log 2: {log2.message} [{log2.level}] {log2.tags}")
print()

# 5. Metadata for custom processing
print("5. Field metadata:")

@dataclass
class Product:
    name: str = field(metadata={"db_column": "product_name"})
    price: float = field(metadata={"db_column": "unit_price", "currency": "USD"})
    quantity: int = field(default=0, metadata={"db_column": "stock_qty"})

from dataclasses import fields

product = Product("Widget", 9.99, 100)
print("   Field metadata:")
for f in fields(product):
    print(f"   - {f.name}: {f.metadata}")

Output

Click Run to execute your code

Never Use Mutable Defaults Directly

Using items: list = [] would share one list across all instances! Always use field(default_factory=list) for mutable defaults like lists, dicts, or sets. Python raises ValueError if you try to use a mutable default directly.

Frozen Dataclasses & __post_init__

Frozen dataclasses are immutable - attempting to modify fields raises an error. The __post_init__ method runs after __init__ completes, perfect for validation or computing derived fields.

# Frozen Dataclasses and __post_init__

print("=== Frozen Dataclasses & __post_init__ ===\n")

from dataclasses import dataclass, field

# 1. Frozen (immutable) dataclasses
print("1. Frozen dataclasses:")

@dataclass(frozen=True)
class Point:
    x: float
    y: float

p = Point(3.0, 4.0)
print(f"   Point: {p}")

# Attempting to modify raises FrozenInstanceError
try:
    p.x = 5.0
except Exception as e:
    print(f"   Cannot modify: {type(e).__name__}")
print()

# 2. Frozen dataclasses are hashable (can be dict keys, set members)
print("2. Frozen dataclasses are hashable:")

@dataclass(frozen=True)
class Color:
    r: int
    g: int
    b: int

# Use as dictionary keys
color_names = {
    Color(255, 0, 0): "Red",
    Color(0, 255, 0): "Green",
    Color(0, 0, 255): "Blue"
}

print(f"   Color(255, 0, 0) = {color_names[Color(255, 0, 0)]}")
print(f"   Colors in set: {len(set([Color(255, 0, 0), Color(255, 0, 0), Color(0, 255, 0)]))}")
print()

# 3. __post_init__ for computed fields
print("3. __post_init__ for computed values:")

@dataclass
class Rectangle:
    width: float
    height: float
    area: float = field(init=False)
    perimeter: float = field(init=False)

def __post_init__(self):
        self.area = self.width * self.height
        self.perimeter = 2 * (self.width + self.height)

rect = Rectangle(5.0, 3.0)
print(f"   Rectangle: {rect}")
print()

# 4. __post_init__ for validation
print("4. Validation in __post_init__:")

@dataclass
class Temperature:
    celsius: float

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

temp = Temperature(25.0)
print(f"   Valid: {temp}")

try:
    invalid = Temperature(-300)
except ValueError as e:
    print(f"   Invalid: {e}")
print()

# 5. __post_init__ with InitVar for init-only variables
print("5. InitVar for init-only variables:")

from dataclasses import InitVar

@dataclass
class User:
    name: str
    password: InitVar[str]  # Passed to __init__ but NOT stored
    password_hash: str = field(init=False)

def __post_init__(self, password):
        # Hash the password (simplified)
        self.password_hash = f"hash_{len(password)}_{password[:2]}***"

user = User("alice", "secret123")
print(f"   User: {user}")
print(f"   Has 'password' attribute: {hasattr(user, 'password')}")  # False!
print(f"   Has 'password_hash' attribute: {hasattr(user, 'password_hash')}")  # True
print()

# 6. Frozen with __post_init__
print("6. Frozen dataclass with computed fields:")

@dataclass(frozen=True)
class Vector:
    x: float
    y: float
    magnitude: float = field(init=False)

def __post_init__(self):
        # For frozen, use object.__setattr__ in __post_init__
        object.__setattr__(self, 'magnitude', (self.x**2 + self.y**2)**0.5)

v = Vector(3.0, 4.0)
print(f"   Vector: {v}")
print(f"   Magnitude: {v.magnitude}")  # 5.0 (3-4-5 triangle)

Output

Click Run to execute your code

InitVar for Init-Only Variables

InitVar[T] declares parameters that are passed to __init__ and __post_init__ but not stored as instance attributes. Use this for values needed during initialization but shouldn't be kept (like passwords to hash).

Advanced Features

Dataclasses support ordering, inheritance, conversion to dict/tuple, memory-efficient slots, and keyword-only arguments. These features make dataclasses suitable for complex real-world applications.

# Advanced Dataclass Features

print("=== Advanced Dataclass Features ===\n")

from dataclasses import dataclass, field, asdict, astuple

# 1. Ordering with order=True
print("1. Automatic ordering:")

@dataclass(order=True)
class Version:
    major: int
    minor: int
    patch: int

def __str__(self):
        return f"{self.major}.{self.minor}.{self.patch}"

versions = [
    Version(2, 0, 0),
    Version(1, 9, 5),
    Version(1, 10, 0),
    Version(2, 1, 0),
]

print(f"   Unsorted: {[str(v) for v in versions]}")
print(f"   Sorted: {[str(v) for v in sorted(versions)]}")
print()

# 2. Custom sort key with sort_index
print("2. Custom sort key:")

@dataclass(order=True)
class Student:
    sort_index: float = field(init=False, repr=False)
    name: str
    gpa: float

def __post_init__(self):
        # Sort by GPA descending (negate for reverse)
        self.sort_index = -self.gpa

students = [
    Student("Alice", 3.8),
    Student("Bob", 3.5),
    Student("Charlie", 3.9),
]

print(f"   By GPA (descending): {[s.name for s in sorted(students)]}")
print()

# 3. Inheritance
print("3. Dataclass inheritance:")

@dataclass
class Animal:
    name: str
    age: int

@dataclass
class Dog(Animal):
    breed: str

def bark(self):
        return f"{self.name} says Woof!"

dog = Dog("Buddy", 3, "Labrador")
print(f"   Dog: {dog}")
print(f"   {dog.bark()}")
print()

# 4. Converting to dict/tuple
print("4. Conversion utilities:")

@dataclass
class Config:
    host: str
    port: int
    debug: bool = False

config = Config("localhost", 8080, True)

# Convert to dictionary
config_dict = asdict(config)
print(f"   As dict: {config_dict}")

# Convert to tuple
config_tuple = astuple(config)
print(f"   As tuple: {config_tuple}")

# Create from dict (using unpacking)
new_config = Config(**config_dict)
print(f"   From dict: {new_config}")
print()

# 5. Slots for memory efficiency (Python 3.10+)
print("5. Using slots (Python 3.10+):")

@dataclass(slots=True)
class Coordinate:
    x: float
    y: float
    z: float

coord = Coordinate(1.0, 2.0, 3.0)
print(f"   Coordinate: {coord}")
print(f"   Has __slots__: {hasattr(Coordinate, '__slots__')}")
# Cannot add dynamic attributes with slots
try:
    coord.w = 4.0
except AttributeError as e:
    print(f"   Cannot add new attribute: {type(e).__name__}")
print()

# 6. kw_only for keyword-only arguments (Python 3.10+)
print("6. Keyword-only arguments (Python 3.10+):")

@dataclass(kw_only=True)
class DatabaseConfig:
    host: str
    port: int
    username: str
    password: str

# Must use keyword arguments
db = DatabaseConfig(host="localhost", port=5432, username="admin", password="secret")
print(f"   Config: DatabaseConfig(host='{db.host}', port={db.port}, ...)")
print()

# 7. Practical example: API response
print("7. Practical example - API Response:")

from typing import List, Optional
from datetime import datetime

@dataclass
class APIResponse:
    status: int
    data: dict = field(default_factory=dict)
    errors: List[str] = field(default_factory=list)
    timestamp: datetime = field(default_factory=datetime.now)
    request_id: Optional[str] = None

@property
    def success(self) -> bool:
        return 200 <= self.status < 300

def to_dict(self) -> dict:
        return {
            "status": self.status,
            "success": self.success,
            "data": self.data,
            "errors": self.errors,
            "timestamp": self.timestamp.isoformat(),
            "request_id": self.request_id
        }

response = APIResponse(200, {"user": "alice"}, request_id="abc-123")
print(f"   Success: {response.success}")
print(f"   Response dict keys: {list(response.to_dict().keys())}")

Output

Click Run to execute your code

Python 3.10+ Features

slots=True reduces memory usage and prevents adding dynamic attributes. kw_only=True forces all arguments to be keyword-only, improving code readability for classes with many fields.

Common Mistakes

1. Using mutable default values directly

# Wrong - shared mutable default!
@dataclass
class BadInventory:
    items: list = []  # ValueError! Python prevents this

# Correct - each instance gets its own list
@dataclass
class GoodInventory:
    items: list = field(default_factory=list)

2. Putting defaults before non-defaults

# Wrong - defaults must come after non-defaults!
@dataclass
class BadOrder:
    status: str = "pending"  # Default
    order_id: str            # No default - TypeError!

# Correct - non-defaults first
@dataclass
class GoodOrder:
    order_id: str            # Required
    status: str = "pending"  # Optional

# Alternative - use field(default=...) for complex ordering
@dataclass
class FlexibleOrder:
    status: str = field(default="pending")
    order_id: str = field(default_factory=lambda: "ORD-001")

3. Forgetting frozen dataclasses need object.setattr in __post_init__

# Wrong - can't set attributes on frozen instance
@dataclass(frozen=True)
class BadVector:
    x: float
    y: float
    magnitude: float = field(init=False)

    def __post_init__(self):
        self.magnitude = (self.x**2 + self.y**2)**0.5  # FrozenInstanceError!

# Correct - use object.__setattr__ for frozen
@dataclass(frozen=True)
class GoodVector:
    x: float
    y: float
    magnitude: float = field(init=False)

    def __post_init__(self):
        object.__setattr__(self, 'magnitude', (self.x**2 + self.y**2)**0.5)

4. Inheriting from non-dataclass with defaults

# Problem - parent has defaults, child has required fields
@dataclass
class Parent:
    name: str = "Unknown"

@dataclass
class Child(Parent):
    age: int  # TypeError! Non-default follows default

# Solution 1 - give child fields defaults too
@dataclass
class Child(Parent):
    age: int = 0

# Solution 2 - use field() with kw_only in Python 3.10+
@dataclass
class Parent:
    name: str = "Unknown"

@dataclass
class Child(Parent):
    age: int = field(kw_only=True)  # Now works!

5. Using dataclass when attrs or namedtuple would be better

# Dataclass might be overkill for simple cases
from dataclasses import dataclass

@dataclass
class Point:  # Fine, but consider alternatives
    x: int
    y: int

# For simple immutable data, NamedTuple is lighter
from typing import NamedTuple

class Point(NamedTuple):
    x: int
    y: int

# For more features (validators, converters), use attrs
import attrs

@attrs.define
class Point:
    x: int = attrs.field(validator=attrs.validators.instance_of(int))
    y: int = attrs.field(validator=attrs.validators.instance_of(int))

# Rule of thumb:
# - NamedTuple: simple immutable records
# - dataclass: most cases, stdlib solution
# - attrs: need validation, converters, advanced features

Exercise: E-Commerce Product System

Task: Create a product management system using dataclasses.

Requirements:

Product dataclass with sku, name, price, quantity, category, and total_value() method
Order dataclass with items list (default_factory), discount (hidden from repr), and total() method
Address frozen dataclass that can be used as dict keys

Output

Click Run to execute your code

Show Solution

from dataclasses import dataclass, field
from typing import List

@dataclass
class Product:
    sku: str
    name: str
    price: float
    quantity: int = 0
    category: str = "General"

    def total_value(self) -> float:
        return self.price * self.quantity


@dataclass
class Order:
    order_id: str
    customer: str
    items: List[Product] = field(default_factory=list)
    discount: float = field(default=0.0, repr=False)

    def add_item(self, product: Product):
        self.items.append(product)

    def subtotal(self) -> float:
        return sum(item.price for item in self.items)

    def total(self) -> float:
        return self.subtotal() - self.discount


@dataclass(frozen=True)
class Address:
    street: str
    city: str
    zip_code: str
    country: str = "USA"


# Test
p1 = Product("SKU001", "Laptop", 999.99, 2)
p2 = Product("SKU002", "Mouse", 29.99, 5)
p3 = Product("SKU003", "Keyboard", 79.99, 3, "Electronics")

print("Products:")
print(f"  {p1}")
print(f"  Total value: ${p1.total_value():.2f}")

order = Order("ORD-001", "Alice")
order.add_item(p1)
order.add_item(p2)
order.add_item(p3)

print(f"\nOrder: {order.order_id}")
print(f"  Items: {len(order.items)}")
print(f"  Subtotal: ${order.subtotal():.2f}")
order.discount = 100.00
print(f"  After $100 discount: ${order.total():.2f}")

addr1 = Address("123 Main St", "Boston", "02101")
addr2 = Address("123 Main St", "Boston", "02101")
print(f"\nAddress: {addr1}")
print(f"  addr1 == addr2: {addr1 == addr2}")
print(f"  Hashable: {hash(addr1) == hash(addr2)}")

Summary

@dataclass auto-generates __init__, __repr__, __eq__ from type-annotated fields
Use field(default_factory=list) for mutable defaults
field(repr=False, compare=False) controls which methods include a field
frozen=True creates immutable, hashable dataclasses
__post_init__ runs after init for validation or computed fields
InitVar[T] declares init-only variables not stored as attributes
order=True adds comparison methods (__lt__, __gt__, etc.)
asdict() and astuple() convert to dict/tuple
Python 3.10+: slots=True, kw_only=True for more control

What's Next?

You've completed the Object-Oriented Programming module! Next, explore Iterators & Generators to learn about lazy evaluation, the iterator protocol, yield, and memory-efficient data processing.

Previous Abstract Classes

Next Iterators

What @dataclass Generates

Dataclass Basics

Type Hints Are Required, Not Enforced

Dataclass Fields

Never Use Mutable Defaults Directly

Frozen Dataclasses & __post_init__

InitVar for Init-Only Variables

Advanced Features

Python 3.10+ Features

Common Mistakes

1. Using mutable default values directly

2. Putting defaults before non-defaults

3. Forgetting frozen dataclasses need object.__setattr__ in __post_init__

4. Inheriting from non-dataclass with defaults

5. Using dataclass when attrs or namedtuple would be better

Exercise: E-Commerce Product System

Summary

What's Next?

Enjoying these tutorials?

3. Forgetting frozen dataclasses need object.setattr in __post_init__