VFlash: Fast, Accurate Visual Planning via Flash Primitive Decoding
u_Unrolled
D1: CS & Systems Foundations · Classes, Dataclasses and Type Hints — Modelling Your Domain
Phase 1/Domain 1/Lesson 13

Classes, Dataclasses and Type Hints — Modelling Your Domain

15 min read·Foundational·Free lesson
Classes, Dataclasses and Type Hints — Modelling Your Domain

The incident. A request dict travels through eight functions. One of them sets req["temprature"] = 0 to make answers deterministic for a compliance customer. The typo creates a new key; the real temperature stays at 0.9. For three weeks, the "deterministic" customer gets random answers. No error was ever raised, because a dict accepts any key.

You already know: dicts (Dicts and sets), closures and decorators (Decorators and context managers).


1. Classes: data plus behaviour

The question. How do you bundle data with the operations that keep it valid?

Start from nothing. A class is a blueprint; each instance is an object built from it. __init__ sets up a new instance's attributes, and methods are functions that receive the instance as self. The class can enforce rules (invariants) so that invalid states can't exist.

python
class TokenBudget:
    """Tracks token spend for one user and refuses to go over the limit."""

    def __init__(self, user, limit):
        if limit <= 0:
            raise ValueError("limit must be positive")
        self.user = user
        self.limit = limit
        self.used = 0

    def spend(self, tokens):
        if self.used + tokens > self.limit:
            raise RuntimeError(f"{self.user}: budget exceeded")
        self.used += tokens

    @property
    def remaining(self):              # computed on access, looks like an attribute
        return self.limit - self.used

    def __repr__(self):               # how the object prints while debugging
        return f"TokenBudget({self.user!r}, used={self.used}/{self.limit})"

budget = TokenBudget("asha", 1000)
budget.spend(400)
print(budget, budget.remaining)
try:
    budget.spend(700)
except RuntimeError as err:
    print(err)

This prints TokenBudget('asha', used=400/1000) 600, then asha: budget exceeded. Methods named with double underscores (dunder methods) like __repr__, __eq__ and __len__ plug your class into Python's built-in behaviour.

the TokenBudget class with __init__ (validate, then set), spend (check before changing state), the remaining property, __repr__ and a from_env classmethod; beside it, an instance for asha (used 400 of 1000, remaining 600) and spend(700) refused with the state unchanged.
Diagram— the TokenBudget class with __init__ (validate, then set), spend (check before changing state), the remaining property, __repr__ and a from_env classmethod; beside it, an instance for asha (used 400 of 1000, remaining 600) and spend(700) refused with the state unchanged.

A real-world pattern: alternative constructors. Services build the same object from several sources: environment variables in production, a dict in tests, a YAML file locally. A @classmethod named from_… keeps the parsing out of __init__ and the validation in one place:

python
class Settings:
    def __init__(self, model, timeout_s, max_retries):
        if timeout_s <= 0:
            raise ValueError("timeout_s must be positive")
        self.model, self.timeout_s, self.max_retries = model, timeout_s, max_retries

    @classmethod
    def from_env(cls, env):
        """Alternative constructor: build validated settings from environment-style strings."""
        return cls(
            model=env.get("MODEL", "small"),
            timeout_s=float(env.get("TIMEOUT_S", "30")),
            max_retries=int(env.get("MAX_RETRIES", "2")),
        )

    def __repr__(self):
        return f"Settings(model={self.model!r}, timeout_s={self.timeout_s}, max_retries={self.max_retries})"

print(Settings.from_env({}))
print(Settings.from_env({"MODEL": "large", "TIMEOUT_S": "12.5"}))
try:
    Settings.from_env({"TIMEOUT_S": "0"})
except ValueError as err:
    print("ValueError:", err)

With no environment, you get the defaults: Settings(model='small', timeout_s=30.0, max_retries=2). Overrides arrive as strings and are converted (timeout_s=12.5). An invalid value fails at start-up with ValueError: timeout_s must be positive, not on the first request an hour later. You'd call it as Settings.from_env(os.environ). In tests, pass a plain dict.

In production. Standard-library examples of the same idea are dict.fromkeys, datetime.fromisoformat and int.from_bytes. Configuration libraries (pydantic-settings, for example) generate this kind of from_env loading and validation for you. Whichever you use, failing fast at start-up on bad config is far cheaper than failing on traffic.

From production

A service reads TIMEOUT_S from the environment inside every request handler with float(os.environ['TIMEOUT_S']). A deploy ships with TIMEOUT_S unset.

What happens, and what's the better design?

  1. Python uses a default of 30 automatically
  2. Only the first request fails
  3. The environment variable is read from a cache
  4. Every request fails with KeyError at runtime; parse and validate settings once at start-up (e.g. Settings.from_env) so the deploy fails immediately with a clear error
Show the answer

D. Every request fails with KeyError at runtime; parse and validate settings once at start-up (e.g. Settings.from_env) so the deploy fails immediately with a clear error — Reading config inside handlers moves config errors to request time, for every request. Parsing once at start-up, with defaults and validation, makes a bad deploy fail fast, usually before it receives traffic.

2. Dataclasses: classes for data, without boilerplate

The question. Do you have to write __init__, __repr__ and __eq__ by hand for every record?

Start from nothing. @dataclass generates them from annotated fields. frozen=True makes instances immutable (and hashable), and __post_init__ is where validation goes. A misspelled field is now an error, which fixes the incident:

python
from dataclasses import dataclass, field, replace

@dataclass(frozen=True)
class GenerationConfig:
    model: str = "small"
    temperature: float = 0.7
    max_tokens: int = 256
    stop: tuple = ()

    def __post_init__(self):
        if not 0 <= self.temperature <= 2:
            raise ValueError(f"temperature {self.temperature} out of range")

base = GenerationConfig()
strict = replace(base, temperature=0.0)        # a modified copy; base is untouched
print(base)
print(strict, strict == GenerationConfig(temperature=0.0))

try:
    GenerationConfig(temprature=0)             # the incident's typo
except TypeError as err:
    print("TypeError:", err)

@dataclass
class Conversation:
    user: str
    messages: list = field(default_factory=list)   # a fresh list per instance

a, b = Conversation("asha"), Conversation("ravi")
a.messages.append("hi")
print(a.messages, b.messages)
  • replace returns a modified copy, the safe way to "change" a frozen object.
  • The typo raises a TypeError ("unexpected keyword argument 'temprature'") the moment the config is built.
  • field(default_factory=list) is the dataclass answer to the mutable-default trap: each instance gets its own list (['hi'] []).
a raw dict accepting a typo key silently, versus a frozen dataclass rejecting it at construction, with type checking catching it before the code even runs.
Diagram— a raw dict accepting a typo key silently, versus a frozen dataclass rejecting it at construction, with type checking catching it before the code even runs.

From production

A feature store returns rows as dicts. A model-serving bug traces back to row['user_age'] sometimes being a string ('34') and sometimes an int.

Which change most directly stops this class of bug at the boundary?

  1. Convert all values to strings
  2. Wrap every use in try/except
  3. Add more comments describing the row format
  4. Parse each row once into a dataclass (or Pydantic model) that validates and converts types in one place
Show the answer

D. Parse each row once into a dataclass (or Pydantic model) that validates and converts types in one place — Validate and convert where data enters your code. After that, everything downstream can trust the types. Validation libraries like Pydantic do the conversion and error reporting for you.

3. Type hints and static checking

The question. How do you catch type mistakes before running the code?

Start from nothing. Type hints annotate what a function expects and returns: def f(x: int) -> str:. Python itself ignores them at runtime. Tools like mypy or pyright read them and report mismatches in your editor and in CI. Useful forms: list[str], dict[str, int], Optional[X] (X or None), Literal["a", "b"].

python
from typing import Optional, Literal

Role = Literal["system", "user", "assistant"]

def last_message(history: list[dict[str, str]], role: Role) -> Optional[str]:
    for msg in reversed(history):
        if msg["role"] == role:
            return msg["content"]
    return None

history = [{"role": "user", "content": "hi"}, {"role": "assistant", "content": "hello!"}]
print(last_message(history, "assistant"), last_message(history, "system"))
print(last_message.__annotations__["return"])

This prints hello! None. The hints don't change behaviour, but last_message(history, "admin") would be flagged by a type checker, and every caller is reminded to handle the None case.

write code → type check (mypy/pyright in CI) → run (Python ignores hints) → boundary (validate JSON, env) → core logic (trusts the types); type checking catches last_message(history, "admin") before running, boundary validation turns "512" into 512, and a value from untyped JSON slips past both as a deep TypeError.
Diagram— write code → type check (mypy/pyright in CI) → run (Python ignores hints) → boundary (validate JSON, env) → core logic (trusts the types); type checking catches last_message(history, "admin") before running, boundary validation turns "512" into 512, and a value from untyped JSON slips past both as a deep TypeError.

What hints can't do: check data at runtime. Type checkers read your source code. They can't see what an API, a form or a JSON file will send at runtime, and Python doesn't enforce hints when the program runs:

python
import json

def tokens_left(limit: int, used: int) -> int:
    return limit - used

print(tokens_left(1000, 250))
try:
    print(tokens_left("1000", 250))          # hints are not checked at runtime
except TypeError as err:
    print("TypeError at runtime:", err)

payload = json.loads('{"user": "asha", "max_tokens": "512"}')   # external JSON: types not guaranteed

def parse_request(raw: dict) -> dict:
    """Validate and convert at the boundary; everything after this can trust the types."""
    max_tokens = int(raw["max_tokens"])
    if not 1 <= max_tokens <= 4096:
        raise ValueError("max_tokens out of range")
    return {"user": str(raw["user"]), "max_tokens": max_tokens}

req = parse_request(payload)
print(req, type(req["max_tokens"]).__name__)
  • The typed call returns 750. Passing "1000" runs anyway, and only fails inside the subtraction: unsupported operand type(s) for -: 'str' and 'int'. A type checker would have flagged a literal "1000", but not a value that came from JSON.
  • parse_request converts the string "512" to the int 512 at the boundary. After that, the rest of the code can trust the types that the hints describe.

In production. This is the split most Python services use. Type hints plus mypy or pyright in CI cover the code you wrote. A validation layer at every boundary covers data you didn't write. FastAPI builds that layer from your type hints using Pydantic, which is why a request body with "max_tokens": "abc" gets a 422 error with a clear message instead of a crash deep in your handler. LLM tool-calling and structured-output features use the same idea: a JSON schema for the model's output, validated before your code trusts it.

From production

A function is annotated def charge(amount_cents: int). mypy passes in CI. In production, a webhook passes payload['amount'], which the provider sends as the string "1999".

What happens, and where should the fix go?

  1. mypy prevented this in CI, so nothing happens
  2. Python converts it to int automatically
  3. Hints aren't enforced at runtime; the string flows into arithmetic and fails (or misbehaves) deep in the code. Parse and validate the webhook payload at the boundary
  4. The webhook is rejected by the HTTP server
Show the answer

C. Hints aren't enforced at runtime; the string flows into arithmetic and fails (or misbehaves) deep in the code. Parse and validate the webhook payload at the boundary — Static checkers can't know what external JSON contains. Validate and convert at the edge (Pydantic, a dataclass with __post_init__, or a parse function) so internal code receives the types its hints promise.

4. Protocols and enums: flexible, explicit designs

The question. How do you accept "anything that can do X" without forcing a common base class?

Start from nothing. A Protocol describes the methods an object must have. Any class with those methods matches, with no inheritance needed (structural typing, or "duck typing" that a checker can verify). It's how you make a model provider swappable. An Enum gives a fixed set of named values, so a status can't be a misspelled string.

python
from typing import Protocol
from enum import Enum

class LLM(Protocol):
    def complete(self, prompt: str) -> str: ...

class FakeLLM:                       # no inheritance from LLM needed
    def complete(self, prompt: str) -> str:
        return prompt.upper()

class EchoLLM:
    def complete(self, prompt: str) -> str:
        return prompt

class Status(Enum):
    QUEUED = "queued"
    DONE = "done"
    FAILED = "failed"

def run(llm: LLM, prompt: str) -> tuple[str, Status]:
    try:
        return llm.complete(prompt), Status.DONE
    except Exception:
        return "", Status.FAILED

for llm in (FakeLLM(), EchoLLM()):
    out, status = run(llm, "hello")
    print(type(llm).__name__, out, status, status.value)
print(Status("done") is Status.DONE)

Both fake models fit the LLM protocol, so tests can swap in a fake without touching run. Status("done") looks up the member by value, which is handy when reading from a database.

the LLM protocol (complete(prompt) -> str) matched by shape, with no inheritance, by FakeLLM (tests), EchoLLM (debugging) and a ProviderAdapter wrapping a real SDK; run(llm, prompt) accepts any of them and returns a Status enum member.
Diagram— the LLM protocol (complete(prompt) -> str) matched by shape, with no inheritance, by FakeLLM (tests), EchoLLM (debugging) and a ProviderAdapter wrapping a real SDK; run(llm, prompt) accepts any of them and returns a Status enum member.

Why this design pays off in AI codebases. Model providers change prices, rate limits and APIs often, and teams regularly route different tasks to different models. Code that imports one vendor's SDK in 40 places is expensive to change. Code that depends on a three-method protocol needs one new adapter. The same seam makes the test suite fast and free: unit tests use a fake that returns canned answers, and a few separate integration tests hit the real provider.

In production. LLM gateways and orchestration libraries are built around exactly this kind of interface: one complete/chat shape, many provider adapters behind it. Enums play the same role for state. Request statuses, tool names and message roles stored as enums (or Literal types) can't drift into "done", "Done" and "completed" across services. When you store them, store the .value and parse it back with Status(value).

From production

Your code calls OpenAI directly in 40 places. Leadership wants to try another provider, and tests currently make real API calls.

Which design change helps both problems?

  1. Copy the 40 call sites and edit them for the new provider
  2. Add a global flag USE_OTHER_PROVIDER
  3. Use inheritance from the OpenAI client class
  4. Define a small Protocol (e.g. complete(prompt) -> str), write one adapter per provider, and pass the model in; tests pass a fake
Show the answer

D. Define a small Protocol (e.g. complete(prompt) -> str), write one adapter per provider, and pass the model in; tests pass a fake — Depending on a small interface instead of a concrete client makes providers swappable and tests fast and free. Each provider's quirks live in one adapter.


Check yourself

  1. What is self in a method?
  2. What three methods does @dataclass generate for you?
  3. Do type hints change what Python does at runtime?
  4. What does a Protocol let you do that a base class doesn't require?
  5. Why doesn't a passing mypy run protect you from bad values in a webhook payload?
  6. What does a from_env classmethod give you over reading environment variables inside handlers?
Answers
  1. The instance the method was called on.
  2. __init__, __repr__ and __eq__ (plus __hash__ when frozen).
  3. No. They're read by tools like mypy and pyright, editors, and some libraries; the interpreter doesn't enforce them.
  4. Accept any object with the right methods, with no inheritance: structural typing that a type checker can verify.
  5. mypy checks your source code, not runtime data. External JSON can contain any types, so it needs validation at the boundary.
  6. Parsing and validation happen once, at start-up, in one place: bad config fails the deploy immediately, and tests can pass a plain dict.

Exercise

Model a chat request as a frozen dataclass ChatRequest(user, messages, max_tokens) where messages is a tuple of Message(role, content) dataclasses. Validate that role is one of system/user/assistant, max_tokens is between 1 and 8192, and the last message is from the user. Add a method with_reply(text) that returns a new request with an assistant message appended.

Solution
python
from dataclasses import dataclass, replace

ROLES = {"system", "user", "assistant"}

@dataclass(frozen=True)
class Message:
    role: str
    content: str

    def __post_init__(self):
        if self.role not in ROLES:
            raise ValueError(f"bad role {self.role!r}")

@dataclass(frozen=True)
class ChatRequest:
    user: str
    messages: tuple
    max_tokens: int = 512

    def __post_init__(self):
        if not 1 <= self.max_tokens <= 8192:
            raise ValueError("max_tokens out of range")
        if not self.messages or self.messages[-1].role != "user":
            raise ValueError("last message must be from the user")

    def with_reply(self, text):
        return replace(self, messages=self.messages + (Message("assistant", text),))

req = ChatRequest("asha", (Message("system", "Be brief."), Message("user", "What is a GIL?")))
print(len(req.messages), req.messages[-1].role)

for bad in [lambda: Message("admin", "x"), lambda: ChatRequest("asha", (), 10)]:
    try:
        bad()
    except ValueError as err:
        print("rejected:", err)

try:
    req.with_reply("A lock.")
except ValueError as err:
    print("rejected:", err)

with_reply builds a request whose last message is from the assistant, so the request's own validation rejects it: the invariant "a request ends with a user turn" holds everywhere, automatically. In a real design the reply would go into a separate Conversation type, a good sign that the types are telling you something about the domain.


This unlocks:

  • Errors, logging, testing and packaging — proving these classes behave, and shipping them as a package.
  • Async Python — typed async clients built on the same Protocol idea.