python-adapters-failure

name	python-adapters-failure
description	Fires when a boundary crossing is about to be hand-rolled instead of built as the matching construct in python-adapters-success — a before-validator that indexes/renames/routes/computes on raw foreign data, a try/except catching Exception or ValidationError or running multiple statements in its except body, or .model_dump/.model_dump_json called anywhere but a route reply or client binding.

Adapters — failure patterns

Three ways a boundary crossing gets hand-rolled instead of built as a foreign model, contract model, or ordered union (python-adapters-success).

Pre-construction munging

A before-validator outside an ordered-union file, or one that indexes, renames, routes, or computes rather than the bare wrap, is data-fixing smuggled ahead of construction. The crossing the model performs in one call is being done by hand first, so the value that reaches construction is already unprovenly reshaped.

A before-validator that indexes, renames, routes, or computes is an alias, a path, or a nested model not yet written:

• a key rename is Field(alias=...);
• data wrapped at one key is validation_alias, nested wrappers an AliasPath, the wrapper modeled and never indexed past;
• nested structure is a nested foreign model.

The only legal before-validator is the ordered union's wrap: a single line on the failure variant that places the bare input under its field name so the variants can be attempted, with a recorded substrate run showing the declarative inventory refuses the shape. One return, constant keys, the input as every value.

@model_validator(mode="before")
def fix(cls, v):
    v["price"] = v.pop("px")   # a rename: Field(alias="px") on the price field
    return v

Swallowed failure

A try/except wider than the single capture form turns failure into procedure: catching Exception or ValidationError, or running a multi-statement except body, instead of letting the failure propagate or constructing it as a value.

One question routes every failure: did the domain say no, or did the proof fail? A construction refusal proves nothing, is never caught, and propagates; catching ValidationError manufactures the unproven value. A domain no is a value, modeled through the ordered union: the capture lives in a verb as one call assigned, each declared exception assigned to the same variable, then ordered-union construction from that variable.

try:
    result = call()
except Exception:
    result = None   # failure erased: let a proof failure propagate, or capture a declared exception and feed the ordered union's constructor

Serialization in the domain

.model_dump or .model_dump_json turns a proven value into a dict or JSON: the crossing out of the application. That crossing belongs only at the edge, where the program meets the wire. Inside the domain a value stays whole, a constructed fact moving between constructions; the domain hands the edge that whole value, never a serialized one, and never reaches past the edge to the transport itself.

The two legal serialization sites are the route reply (api/) and the client binding (service/). Everywhere else, in a concept model, a derivation, a verb, the consistency model, a .model_dump/.model_dump_json flattens a value that is still moving inside the program. A verb emits the proven value itself through its client fields and lets the binding serialize at the wire; it never builds the JSON itself, and never hands JSON forward to the binding or the transport.

def book(self, fill: VenueFill) -> None:
    self.latest = Position(prior=self.latest, fill=fill)
    self.bus.publish(self.latest.model_dump())   # publish self.latest whole; let the binding serialize at the wire