json & Serialization

The json module encodes Python objects to JSON text and parses JSON into dict/list scalars. Customize with default encoders and object_hook for round-trips - for APIs prefer Pydantic 2 at boundaries.

Recipe

import json
from datetime import datetime, timezone
 
def default(obj):
    if isinstance(obj, datetime):
        return obj.astimezone(timezone.utc).isoformat()
    raise TypeError(type(obj))
 
payload = json.dumps({"at": datetime.now(timezone.utc)}, default=default)

When to reach for this:

• Config files and CLI JSON output
• Simple REST without Pydantic overhead
• json.loads on trusted small payloads
• NDJSON log lines
• Interop with JavaScript clients

Working Example

import json
from dataclasses import asdict, dataclass
from datetime import datetime, timezone
from pathlib import Path
 
@dataclass
class Event:
    name: str
    at: datetime
 
def encode_event(obj):
    if isinstance(obj, datetime):
        return obj.isoformat()
    raise TypeError(type(obj))
 
def save_events(path: Path, events: list[Event]) -> None:
    raw = [asdict(e) for e in events]
    path.write_text(json.dumps(raw, default=encode_event, indent=2), encoding="utf-8")
 
def load_events(path: Path) -> list[dict]:
    return json.loads(path.read_text(encoding="utf-8"))
 
events = [Event("login", datetime.now(timezone.utc))]
out = Path("events.json")
save_events(out, events)
print(load_events(out))
out.unlink(missing_ok=True)

What this demonstrates:

• Dataclass -> dict -> JSON pipeline
• Custom default for non-JSON-native types
• Explicit utf-8 file encoding
• Parse returns dicts - validate before use

Deep Dive

JSON Types

Performance

• orjson PyPI faster for hot paths
• json.dumps fine for CLI and config

Gotchas

• float precision - JSON numbers are IEEE doubles. Fix: Decimal as str if money.
• Key type str only - dict keys coerced to str in JSON. Fix: normalize on load.
• Huge file loads - memory spike. Fix: ijson streaming or line-delimited.
• Untrusted input depth - DoS via nested objects. Fix: limit size, use parser with limits.
• datetime naive in JSON - ambiguous. Fix: always UTC ISO with offset.

Alternatives

FAQs

Related

• datetime, zoneinfo & time - encode datetimes
• Pydantic basics - validated models
• pathlib & os - config paths
• Standard Library Best Practices - serialization rules

External Related Links

• Python Standard Library Reference - Complete documentation for built-in modules and functions.
• Real Python - In-depth tutorials, courses, and practical guides.
• Python HOWTOs (Official) - Practical topic-focused guides.
• Fluent Python (2nd Edition) - Intermediate to advanced Python idioms (Luciano Ramalho).
• Python Crash Course (3rd Edition) - Beginner-friendly projects (Eric Matthes).

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.