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.
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.
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:
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.fromisoformatandint.from_bytes. Configuration libraries (pydantic-settings, for example) generate this kind offrom_envloading 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?
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:
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)
replacereturns 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'] []).
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?
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"].
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.
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:
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_requestconverts the string"512"to the int512at 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?
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.
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.
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/chatshape, many provider adapters behind it. Enums play the same role for state. Request statuses, tool names and message roles stored as enums (orLiteraltypes) can't drift into"done","Done"and"completed"across services. When you store them, store the.valueand parse it back withStatus(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?
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
- What is
selfin a method? - What three methods does
@dataclassgenerate for you? - Do type hints change what Python does at runtime?
- What does a Protocol let you do that a base class doesn't require?
- Why doesn't a passing mypy run protect you from bad values in a webhook payload?
- What does a
from_envclassmethod give you over reading environment variables inside handlers?
Answers
- The instance the method was called on.
__init__,__repr__and__eq__(plus__hash__when frozen).- No. They're read by tools like mypy and pyright, editors, and some libraries; the interpreter doesn't enforce them.
- Accept any object with the right methods, with no inheritance: structural typing that a type checker can verify.
- mypy checks your source code, not runtime data. External JSON can contain any types, so it needs validation at the boundary.
- 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
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.