Dataclasses & Pydantic & TypedDict

Introduction

Managing classes primarily used to store data has historically involved a lot of boilerplate: writing __init__, __repr__, and __eq__ methods by hand. Dataclasses (Python 3.7+) and Pydantic solve this, but they serve different purposes. One optimizes for speed and syntax, the other for validation and correctness.

The Boilerplate Killer

class Product:
    def __init__(self, name, price, stock=0):
        self.name = name
        self.price = price
        self.stock = stock

    def __repr__(self):
        return f"Product(name='{self.name}', ...)"

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

p = Product("Widget", 9.99, stock=5)
print(p)
print(p == Product("Widget", 9.99))

Product(name='Widget', ...)
True

from dataclasses import dataclass

@dataclass
class Product:
    name: str
    price: float
    stock: int = 0

# You get for free:
# __init__, __repr__, __eq__, __hash__ (optional)

p = Product("Widget", 9.99, stock=5)
print(p)
print(p == Product("Widget", 9.99, stock=5))

# Types are hints, not rules, nothing
# here is checked at runtime...
print(Product(name=42, price="free"))

Product(name='Widget', price=9.99, stock=5)
True
Product(name=42, price='free', stock=0)

Native Dataclasses

Built into the standard library, dataclasses are lightweight code generators. They generate special methods based on type hints, but they DO NOT validate data at runtime.

from dataclasses import dataclass

@dataclass(frozen=True)
class Config:
    host: str
    port: int

c = Config("localhost", 8080)

try:
    c.host = "127.0.0.1"  # Raises FrozenInstanceError!
except Exception as e:
    print(f"{type(e).__name__}: {e}")

# Also makes the object hashable (usable as dict keys)
print({Config("localhost", 8080): "primary"})

FrozenInstanceError: cannot assign to field 'host'
{Config(host='localhost', port=8080): 'primary'}

Pydantic: Dataclasses on Steroids

Pydantic's BaseModel looks like a dataclass but behaves like a parser. It guarantees that the types of the output model match the types you defined, coercing data where possible.

from pydantic import BaseModel, ValidationError

class User(BaseModel):
    id: int
    name: str = "Anonymous"
    tags: list[str] = []

# 1. Happy path
print(User(id=123, name="Alice"))

# 2. Pydantic validates and converts types
print(User(id="123", tags=["admin"]))

# 3. What it cannot convert, it rejects
try:
    User(id="not-a-number")
except ValidationError as e:
    print(e)

id=123 name='Alice' tags=[]
id=123 name='Anonymous' tags=['admin']
1 validation error for User
id
  Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='not-a-number', input_type=str]
    For further information visit https://errors.pydantic.dev/2.13/v/int_parsing

Two details worth noting. print() on a model uses Pydantic's __str__, which omits the class name, so it reads id=123 name='Alice' rather than the repr form. And the error text above is Pydantic v2's: v1 phrased the same failure as value is not a valid integer, so error messages copied from older tutorials will not match what you see.

When to avoid dataclasses or Pydantic in favor of TypedDict

Sometimes you just want type hints for a regular dictionary without the overhead of a class or runtime validation. In these cases, use TypedDict.

from typing import TypedDict

class UserDict(TypedDict):
    id: int
    name: str

# At runtime, this is just a plain dictionary! Zero overhead.
data: UserDict = {"id": 1, "name": "Alice"}
print(type(data), data)

# Nothing checks the annotation, so a type checker is your only safety net
wrong: UserDict = {"id": "not-an-int", "name": 5}
print(wrong)

<class 'dict'> {'id': 1, 'name': 'Alice'}
{'id': 'not-an-int', 'name': 5}

Head-to-Head Comparison

* Note: Pydantic V2 (written in Rust) is significantly faster than V1, narrowing the gap.

Best Practices