Appearance
3.14.10 — Capstone: The Order Service, End to End, and the Senior Interview Boss Fight
Twenty-five pages ago, python checkout.py was a mystery between pressing Enter and seeing a total. This page puts everything together. First, one complete, runnable order service, about 170 lines, where every line uses something from Chapters 3.13 and 3.14. Then one checkout request, followed from the network socket to the database row and back, with each step pointing to the page that explains it. Finally, the cross-chapter questions that senior Python interviews actually ask, with answers you can defend line by line.
1. The complete service
The service lets a logged-in customer place an order and read their own orders. It reserves stock atomically, refuses unknown fields, never shows one customer another's order, and gives every error the same shape with a request ID. Read it top to bottom. Each block is short, and the walk-through below says which page each idea comes from.
python
import contextvars
import logging
import uuid
from contextlib import asynccontextmanager
from decimal import Decimal
from typing import Annotated
import jwt
from fastapi import Depends, FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse
from fastapi.security import OAuth2PasswordBearer
from pydantic import BaseModel, ConfigDict, Field, SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict
from sqlalchemy import ForeignKey, Numeric, String, select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship, selectinload
# ---------- (1) settings ----------
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_prefix="SHOP_")
database_url: str = "sqlite+aiosqlite:///capstone.db"
jwt_secret: SecretStr = SecretStr("dev-only-secret-change-me-32-bytes!!")
settings = Settings()
request_id_var = contextvars.ContextVar("request_id", default="-")
logger = logging.getLogger("shop.orders")
# ---------- (2) database models ----------
class Base(DeclarativeBase):
pass
class Product(Base):
__tablename__ = "products"
sku: Mapped[str] = mapped_column(String(20), primary_key=True)
price: Mapped[Decimal] = mapped_column(Numeric(10, 2))
stock: Mapped[int]
class Order(Base):
__tablename__ = "orders"
id: Mapped[int] = mapped_column(primary_key=True)
customer_id: Mapped[int]
status: Mapped[str] = mapped_column(String(20), default="pending")
lines: Mapped[list["OrderLine"]] = relationship(cascade="all, delete-orphan", lazy="raise")
class OrderLine(Base):
__tablename__ = "order_lines"
id: Mapped[int] = mapped_column(primary_key=True)
order_id: Mapped[int] = mapped_column(ForeignKey("orders.id"))
sku: Mapped[str] = mapped_column(ForeignKey("products.sku"))
quantity: Mapped[int]
unit_price: Mapped[Decimal] = mapped_column(Numeric(10, 2))
# ---------- (3) API schemas ----------
class LineIn(BaseModel):
model_config = ConfigDict(extra="forbid")
sku: Annotated[str, Field(min_length=3, max_length=20)]
quantity: Annotated[int, Field(ge=1, le=10)]
class OrderIn(BaseModel):
model_config = ConfigDict(extra="forbid")
lines: list[LineIn] = Field(min_length=1, max_length=20)
class LineOut(BaseModel):
model_config = ConfigDict(from_attributes=True)
sku: str
quantity: int
unit_price: Decimal
class OrderOut(BaseModel):
model_config = ConfigDict(from_attributes=True)
id: int
status: str
lines: list[LineOut]
# ---------- (4) domain errors ----------
class OrderError(Exception):
status_code = 400
code = "order_error"
class OutOfStock(OrderError):
status_code = 409
code = "out_of_stock"
class OrderNotFound(OrderError):
status_code = 404
code = "order_not_found"
# ---------- (5) service layer: plain Python, no FastAPI ----------
class OrderService:
def __init__(self, session: AsyncSession):
self.session = session
async def place(self, customer_id: int, lines: list[LineIn]) -> Order:
async with self.session.begin():
order = Order(customer_id=customer_id, lines=[])
for line in lines:
price = (await self.session.execute(
update(Product)
.where(Product.sku == line.sku, Product.stock >= line.quantity)
.values(stock=Product.stock - line.quantity)
.returning(Product.price))).scalar_one_or_none()
if price is None:
raise OutOfStock(f"not enough stock for {line.sku}")
order.lines.append(OrderLine(sku=line.sku, quantity=line.quantity, unit_price=price))
self.session.add(order)
logger.info("order placed id=%s customer=%s", order.id, customer_id)
return order
async def get_for_customer(self, order_id: int, customer_id: int) -> Order:
order = await self.session.scalar(
select(Order)
.where(Order.id == order_id, Order.customer_id == customer_id)
.options(selectinload(Order.lines)))
if order is None:
raise OrderNotFound(f"order {order_id} not found")
return order
# ---------- (6) HTTP wiring ----------
@asynccontextmanager
async def lifespan(app: FastAPI):
engine = create_async_engine(settings.database_url, pool_pre_ping=True)
app.state.sessions = async_sessionmaker(engine, expire_on_commit=False)
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
yield
await engine.dispose()
app = FastAPI(title="Order Service", lifespan=lifespan)
oauth2 = OAuth2PasswordBearer(tokenUrl="token")
@app.middleware("http")
async def request_context(request: Request, call_next):
request_id = request.headers.get("x-request-id") or uuid.uuid4().hex[:8]
token = request_id_var.set(request_id)
try:
response = await call_next(request)
finally:
request_id_var.reset(token)
response.headers["x-request-id"] = request_id
return response
@app.exception_handler(OrderError)
async def order_error(request: Request, exc: OrderError):
return JSONResponse(status_code=exc.status_code,
content={"error": {"code": exc.code, "message": str(exc),
"request_id": request_id_var.get()}})
async def get_session(request: Request):
async with request.app.state.sessions() as session:
yield session
def get_customer_id(token: Annotated[str, Depends(oauth2)]) -> int:
try:
claims = jwt.decode(token, settings.jwt_secret.get_secret_value(), algorithms=["HS256"])
except jwt.InvalidTokenError:
raise HTTPException(401, "could not validate credentials",
headers={"WWW-Authenticate": "Bearer"})
return int(claims["sub"])
def get_order_service(session: Annotated[AsyncSession, Depends(get_session)]) -> OrderService:
return OrderService(session)
CustomerId = Annotated[int, Depends(get_customer_id)]
Orders = Annotated[OrderService, Depends(get_order_service)]
@app.post("/orders", status_code=201)
async def place_order(payload: OrderIn, customer_id: CustomerId, orders: Orders) -> OrderOut:
return await orders.place(customer_id, payload.lines)
@app.get("/orders/{order_id}")
async def get_order(order_id: int, customer_id: CustomerId, orders: Orders) -> OrderOut:
return await orders.get_for_customer(order_id, customer_id)Here is what each block is and where it was taught.
(1)Settings are validated at start-up, and the secret is aSecretStrthat never prints (3.14.2). The request ID lives in a context variable, so concurrent requests never mix (3.13.15).(2)Models useMapped[...],Numericfor money andlazy="raise", so an accidental N+1 load fails loudly instead of silently slowing the page (3.14.6).(3)Schemas are separate for input and output.extra="forbid"rejects smuggled fields.from_attributesreads ORM objects. Only declared fields leave the server (3.14.2, 3.14.3).(4)Domain errors are a small exception hierarchy carrying status and code (3.13.10).(5)The service layer is plain Python. It knows nothing about HTTP, so it can be called from a background worker or a script. Stock is reserved with one conditional atomicUPDATE, and one transaction rolls everything back if any line fails (3.14.6). Ownership is part of the query (3.14.7).(6)HTTP wiring: the lifespan creates one engine per process (3.14.5), the middleware adds request IDs, one handler turns every domain error into the same JSON shape, and dependencies provide the session, the authenticated customer and the service (3.14.4). The endpoints are two lines each.
2. Running it
Seed two products, with one mug in stock, and make tokens for two customers, Asha (ID 1) and Ravi (ID 2). Then:
text
POST /orders Asha {"lines":[{"sku":"MUG","quantity":1},{"sku":"PEN","quantity":2}]} X-Request-ID: req-1
201 {"id":1,"status":"pending","lines":[{"sku":"MUG","quantity":1,"unit_price":"450.00"},{"sku":"PEN","quantity":2,"unit_price":"40.00"}]}
POST /orders Ravi {"lines":[{"sku":"MUG","quantity":1}]} X-Request-ID: req-2
409 {"error":{"code":"out_of_stock","message":"not enough stock for MUG","request_id":"req-2"}}
GET /orders/1 Asha
200 {"id":1,"status":"pending","lines":[…]}
GET /orders/1 Ravi X-Request-ID: req-4
404 {"error":{"code":"order_not_found","message":"order 1 not found","request_id":"req-4"}}
POST /orders Asha {"lines":[{"sku":"PEN","quantity":2}],"discount":50}
422 {"detail":[{"type":"extra_forbidden","loc":["body","discount"],"msg":"Extra inputs are not permitted","input":50}]}
GET /orders/1 (no token)
401 {"detail":"Not authenticated"}
stock afterwards: {'MUG': 0, 'PEN': 98}Every rule held: the last mug sold once, Ravi cannot even learn that Asha's order exists, the smuggled discount was rejected, and stock matches exactly what was sold.
3. One checkout, traced through every layer
Follow Asha's POST /orders from the network to the database and back. Each step names the page that explains it.
- The connection. The kernel accepts the TCP connection. Uvicorn's event loop, sleeping in
epoll, is woken because the socket is readable (3.13.15). - Parsing. Uvicorn parses the HTTP bytes with
httptoolsinto an ASGIscopeand callsawait app(scope, receive, send)(3.14.1). - Middleware. The request enters
ServerErrorMiddleware, thenrequest_context, which setsrequest_id_vartoreq-1in this request's own context (3.14.5). - Routing. Starlette matches
POST /orderstoplace_order, using the routing table that@app.postbuilt at import time, a registration decorator (3.13.5). - The plan. FastAPI runs the dependant plan it built at start-up from the function's signature and type hints with
inspect.signatureandget_type_hints(3.13.4, 3.13.12, 3.14.3). - Dependencies. Depth-first:
oauth2reads theAuthorizationheader,get_customer_idverifies the JWT's signature with a fixed algorithm list and returns1(3.14.7).get_sessionopens a session from the pool, ayielddependency pushed onto an exit stack (3.13.9, 3.14.4).get_order_servicewraps it. Each runs once per request, thanks to the cache. The twodefdependencies run in the thread pool, and theasync defones on the loop. - Validation. The body bytes are validated by the Rust
SchemaValidatorthat Pydantic compiled forOrderInwhen the class was created, by a metaclass (3.13.7, 3.14.2). Quantities are checked, and unknown fields are refused. - The endpoint.
place_orderis awaited on the event loop, because it isasync def(3.14.3). - The transaction.
session.begin()borrows a pooled connection. Eachawait session.execute(...)sends a conditionalUPDATE … RETURNINGand pauses the coroutine, handing the loop to other requests while the database works (3.13.15). The database takes row locks, so a concurrent request for the same mug waits, re-checks and finds no stock (3.14.6). - Objects.
OrderLine(...)objects are created by generated__init__methods, with their attributes managed by SQLAlchemy descriptors (3.13.6, 3.13.7). The prices are exactDecimals, never floats (3.13.3). - Commit. Leaving
session.begin()flushes the order and lines in foreign-key order and commits, before the response is built, so a failed commit would become an error, not a false success (3.14.4). - The response. The returned
Orderis validated againstOrderOutwithfrom_attributes, serialised by Pydantic's Rust core, and filtered to declared fields (3.14.2). - Back out. The response passes back through the middleware, which adds
x-request-id: req-1. Uvicorn writeshttp.response.startandhttp.response.bodyto the socket (3.14.1). - Cleanup. The session dependency's exit code runs after the response is sent, closing the session and returning its connection to the pool. Reference counts drop, and the request's objects are freed immediately (3.13.13).
If Ravi's request arrives at step 9, its UPDATE matches zero rows, OutOfStock is raised inside session.begin(), the transaction rolls back, the exception travels up past the endpoint, and ExceptionMiddleware finds the OrderError handler, which builds the 409 with req-2 from the context variable (3.13.10, 3.14.5).
4. The boss fight: cross-chapter questions
These questions each need two or more pages to answer. They are the kind a senior interview uses to separate people who have built Python services from people who have read about them. Try each one aloud before opening the answer.
StaffWalk me through exactly what happens when an async FastAPI endpoint awaits a database query.
The endpoint is a coroutine running inside a task on Uvicorn's event loop. await session.execute(stmt) goes down through SQLAlchemy's async layer to the driver, which writes the query to the socket and then awaits a future that completes when the reply arrives. That await travels up the chain of coroutines to the task, which yields the future to the event loop, the same mechanism as a generator's yield with send(). The loop is now free. It runs other ready tasks, then sleeps in epoll with a timeout until some socket is readable or a timer is due. When the database reply arrives, the loop marks the future done, schedules the task, and resumes the coroutine at the await with the result. Nothing blocked, no thread was used, and while this request waited, the same thread served many others. Pages: 3.13.9, 3.13.15, 3.14.1, 3.14.6.
StaffList every way a Python service can accidentally share state between requests, and how each one bites.
First, a mutable default argument, created once when def runs and shared by every call. Second, a mutable class attribute, created once when the class body runs and shared by every instance. Third, module-level objects, because a module runs once per process and every importer shares it: caches, lists of seen items and singletons. Fourth, @lru_cache on methods, which keeps self alive and shares results across users if keys are not user-specific. Fifth, a closure capturing a variable rather than a value. Sixth, a thread-local or global used for request data in async code, where thousands of requests share one thread, so values leak between them. Seventh, in-process state that is assumed to be global, such as rate-limit counters and WebSocket hubs, which is actually per worker process. The fixes: None defaults, state in __init__, bounded caches keyed correctly, context variables for request data, and shared stores such as Redis or the database for anything that must be global. Pages: 3.13.2, 3.13.4, 3.13.5, 3.13.6, 3.13.11, 3.13.15, 3.14.4.
StaffYour FastAPI service has low CPU but terrible p99 latency under load. Diagnose it from first principles.
Low CPU with long waits means requests are queued behind something rather than computing. In an async service, the prime suspect is a blocked event loop. One synchronous call inside async def stops every other request on that worker until it finishes. Typical culprits are requests, a synchronous database driver, time.sleep and a large JSON parse. Measure loop lag, with a sleep-and-measure watcher or a metric, and take a py-spy dump of a slow worker to see the blocking frame. Second suspect: pool exhaustion, where requests wait for a database connection because transactions are long or hold connections across external calls. Third: downstream calls without timeouts. Fourth: N+1 queries that only appear with real data. Fix by moving blocking calls to async libraries or to_thread, or making those endpoints def, by shortening transactions, by adding timeouts and bounded retries, and by eager loading. Pages: 3.13.13, 3.13.15, 3.14.3, 3.14.6, 3.14.9.
StaffDesign POST /orders so that a client retrying after a timeout can never create two orders or charge twice.
Require an Idempotency-Key header, a UUID the client generates once per checkout attempt and reuses on every retry. Store keys in a table with a unique constraint on customer ID plus key, along with a hash of the request body, the status and the stored response. In one transaction, insert the key row in a "processing" state; if the unique constraint fails, the key was seen before. If the earlier attempt finished, return the stored response. If the body hash differs, return 422. If it is still processing, return 409 so the client retries later. Otherwise create the order and reserve stock atomically, and write an outbox row for the payment step in the same transaction. Commit before responding. A worker charges the card using the order ID as the payment provider's idempotency key, so a repeated charge is recognised by the provider too. Store the final response against the key, and expire old keys after a retention period. Pages: 3.13.10, 3.14.3, 3.14.5, 3.14.6, 3.14.7.
StaffWhat does free-threaded Python 3.14 change for a FastAPI service, and should we adopt it?
Standard CPython lets one thread run Python bytecode at a time, so a FastAPI worker uses one core for Python work, and def endpoints in the thread pool only overlap their waiting. The free-threaded build removes the GIL, so def endpoints and CPU-bound code in threads can truly run in parallel within one process. That could reduce how many worker processes you need and share caches in memory. Costs: single-threaded code is roughly 5 to 10% slower; every C extension must support free threading or the GIL is switched back on; and data races that the GIL used to hide, in shared dicts, counters and module state, become real bugs. A typical async, I/O-bound FastAPI service gains little, because its bottleneck is waiting, not Python CPU. Adopt only after confirming extension support, auditing shared mutable state, and benchmarking real traffic. Pages: 3.13.13, 3.13.14, 3.14.3, 3.14.9.
StaffA FastAPI worker's memory grows all day. Walk through your investigation.
First separate Python-level growth from process-level growth. Track tracemalloc totals and object counts against the process's resident memory over time. If Python-level allocations grow, compare two tracemalloc snapshots taken an hour apart, grouped by line, which points straight at the allocation site. Typical culprits: an unbounded module-level dict or list, @lru_cache(maxsize=None) on high-variety arguments, @lru_cache on methods keeping instances alive, tasks created and never awaited or stored, a growing WebSocket registry that never removes dead connections, and reference cycles with the collector disabled. If Python memory is flat but the process grows, suspect allocator fragmentation in partly used arenas or a C extension. Recycle workers after N requests while investigating. Fix with bounded caches, weak references where retention is not wanted, and explicit cleanup in finally blocks and yield dependencies. Pages: 3.13.5, 3.13.13, 3.14.8, 3.14.9.
StaffExplain what @app.get('/orders/{order_id}') does, from the decorator syntax down to the first request.
@app.get("/orders/{order_id}") first calls app.get(...) with the path, which returns a decorator, a function waiting for the endpoint. Python then applies it: get_order = decorator(get_order), at import time. The decorator registers a route: it reads inspect.signature(get_order) and the type hints, including Annotated extras, decides that order_id is a path parameter because its name is in the template, builds the dependant tree of all Depends, and creates Pydantic validators for every parameter and for the response model taken from the return annotation. It then returns the original function unchanged, so it can still be called directly. On the first request, Starlette's router matches the path, FastAPI runs the prebuilt plan, converts "42" to 42 or answers 422, resolves dependencies, calls the function, and serialises the result through the response model. Pages: 3.13.4, 3.13.5, 3.13.12, 3.14.2, 3.14.3, 3.14.4.
StaffWhen do you use a dataclass, a Pydantic model and an ORM model, and how does data move between them?
Pydantic models sit at trust boundaries: HTTP request and response bodies, configuration, and messages from queues. They validate and convert untrusted input, and they define exactly what leaves the service. ORM models describe storage: tables, columns, relationships and constraints, with change tracking handled by the session. Dataclasses, often frozen, or plain classes, describe internal domain values that are already trusted, such as a priced line or a money amount, without validation cost. Data flows inward as request JSON, then a Pydantic input model, then a service function, then ORM objects written in a transaction. It flows outward as ORM objects, then a Pydantic output model with from_attributes=True, then JSON. Never return ORM objects without an output model, which leaks columns, and never pass raw dicts through the service layer, which loses the guarantees. Pages: 3.13.8, 3.14.2, 3.14.3, 3.14.6.
StaffWrite and explain an async context manager that times a block and logs it with the current request ID, even when the block fails.
python
import logging
import time
from contextlib import asynccontextmanager
logger = logging.getLogger("shop.timing")
@asynccontextmanager
async def timed(label: str):
start = time.perf_counter()
try:
yield
finally:
elapsed_ms = (time.perf_counter() - start) * 1000
logger.info("%s took %.1f ms", label, elapsed_ms,
extra={"fields": {"request_id": request_id_var.get()}})asynccontextmanager turns the async generator into an object with __aenter__ and __aexit__. The code before yield runs on entry. If the block raises, the exception is thrown into the generator at the yield, so finally still runs and the timing is logged, and because we do not catch it, the exception continues to the caller. The request ID comes from the context variable, so concurrent requests log their own IDs without passing anything. Lazy % formatting means nothing is formatted if the level is disabled. Pages: 3.13.9, 3.13.10, 3.13.15, 3.13.16, 3.14.5, 3.14.9.
StaffThe team proposes rewriting the order service in Go for performance. Respond as the senior engineer in the room.
Start with evidence, not language. Pull the traces: where does a checkout spend its time? In most order services it is database round trips, external payment and shipping calls, and serialisation, not Python's per-instruction speed. If the profile shows waiting, the wins are in fewer and better queries, eager loading, caching, timeouts and concurrency with TaskGroup, and Go would wait just as long. If it shows CPU in Python, check whether the hot path can use Pydantic's Rust core, built-in functions or a vectorised library, or move to a worker pool, and whether more processes would simply solve it at an acceptable cost. A rewrite also discards years of fixed edge cases, and the team's expertise. If one component is genuinely CPU-bound and central, such as a pricing engine, extract just that into a separate service, or a compiled extension, with a clear interface, and measure again. Pages: 3.13.1, 3.13.13, 3.14.6, 3.14.9.
5. Ten sentences a senior Python engineer can defend
- CPython compiles source to bytecode, caches it for imported modules, and interprets it in a specializing evaluation loop. Consistent types keep hot code fast.
- A variable is a label on an object. Assignment never copies, and functions receive labels on the caller's objects.
- Anything created once and mutated later, such as a default argument, a class attribute, a module global or a cache, is shared, and shared mutable state is where Python bugs live.
- Decorators, properties, methods and Pydantic models are not magic. They are closures, descriptors and metaclasses doing ordinary work at definition time.
- A generator is a function whose frame lives on the heap, and
async/awaitis that same pause-and-resume machinery driven by an event loop. - Type hints are not enforced by Python. Static checkers use them to prove your code consistent, and Pydantic and FastAPI use them at run time to validate untrusted data.
- The GIL protects the interpreter, not your data. Threads help waiting, processes help computing, and the free-threaded build changes the trade-off at a measurable cost.
- Never block the event loop. In FastAPI, use
async defwith async libraries, plaindefwith blocking ones, and a process or queue for CPU-heavy work. - Validate at the edges, filter what leaves through output models, keep business logic free of HTTP, and let the database enforce what must always be true.
- Measure before optimising. Profiles, traces, loop lag and query counts beat intuition every time.
Recall
- The capstone layers: settings with
SecretStr, ORM models withlazy="raise", separate input and output schemas withextra="forbid"andfrom_attributes, a domain exception hierarchy, a framework-free service layer with an atomic conditionalUPDATEand an ownership filter, and HTTP wiring through lifespan, middleware, exception handler and dependencies. - One checkout passes through: kernel and
epoll→ Uvicorn parsing → ASGI → middleware and context variable → router from a registration decorator → the dependant plan from signature and hints → dependencies with cache and exit stack → Rust validation →asyncendpoint → awaited queries in one transaction → commit before responding → response-model serialisation → middleware out → socket → cleanup after the response. - The boss-fight themes: await end to end, shared-state bugs, low-CPU high-latency diagnosis, idempotent POST, free-threading, memory growth, decorator-to-route, the three kinds of model, async context managers, and "rewrite in Go".
Self-test: Trace Ravi's failed order from the UPDATE to the 409 response without looking. Name four places shared state can hide in a Python service. Explain why get_order returns 404, not 403, for someone else's order. Give the one-sentence rule for choosing def or async def.
Next: with Python and FastAPI complete, 3.9 puts Python back alongside C, Java, Go and Rust, so you can see what each language would have done differently with this same order service.