python-dataclasses-pydantic

Data Modeling with Dataclasses + Pydantic

Use when a module carries structured records and you want type safety, validation, or clean JSON round-tripping. The two tools overlap but solve different problems: dataclasses are a lightweight typing/memory tool; Pydantic adds runtime validation + serialization at the boundary.

Type-safety with dataclasses

from __future__ import annotations
from dataclasses import dataclass


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

@dataclass(slots=True) reduces memory and prevents accidental attribute typos (an unknown attribute becomes an AttributeError, not a silent new field).

Validation + serialization with Pydantic (v2)

from pydantic import BaseModel, Field


class SkillInput(BaseModel):
    name: str = Field(min_length=3, max_length=64)
    description: str
    tags: list[str] = Field(default_factory=list)
    port: int = Field(ge=1, le=65535)

    @field_validator("name")
    @classmethod
    def _no_whitespace(cls, v: str) -> str:
        v = v.strip()
        if not v:
            raise ValueError("name must not be blank")
        return v

Pydantic v2 is the current API (pydantic ≥ 2.0). Key calls:

• Model.model_validate(data) — validate/coerce a dict or object.
• Model.model_validate_json(s) — parse + validate a JSON string directly.
• model.model_dump() / model.model_dump_json() — serialize to dict / JSON.
• Field(...) — constraints and defaults (min_length, ge, default_factory).
• @field_validator("x") — per-field post-validation transforms/checks.
• @computed_field — a read-only property exposed in model_dump().
• ConfigDict / model_config — e.g. model_config = ConfigDict(frozen=True, extra="forbid").

Nesting composes cleanly: a field whose type is another BaseModel is validated recursively, so you get a typed, validated object graph from JSON in one call.

Decision table: dataclass vs Pydantic

Concern	@dataclass	Pydantic BaseModel
Runtime validation / coercion of inputs	✗ none	✓ automatic, per-field
JSON round-trip	manual asdict/json.dumps	model_dump_json() / model_validate_json
Performance (creation in hot loops)	fast, near-plain-class	slower — validation overhead per instantiation
Mutable default lists/dicts	foot-gun (see Pitfalls)	default_factory handled, but Field(default_factory=...) still required
Immutable value objects	frozen=True	ConfigDict(frozen=True)
Serialization shape control	manual	rich (by_alias, exclude_unset, computed_field)
Syntax/deps	stdlib, zero deps	third-party dependency