OpenAPI & Encoding¶
Schema generation and the JSON encoding layer.
jsonable_encoder(obj: Any, include: set[str] | None = None, exclude: set[str] | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, custom_encoder: dict[type, Callable[[Any], Any]] | None = None, *, _seen: set[int] | None = None) -> Any
Convert complex objects to JSON-serializable types.
Handles Pydantic models, dataclasses, datetime, Decimal, UUID, Enum, Path, sets, frozensets, and nested structures.
Every filter applies at every depth, not only to the top-level
object. exclude={"password"} strips a password key wherever it
appears in the structure; exclude_none drops None-valued keys at
any depth; and exclude_unset / exclude_defaults reach a model
nested inside a dict or list, not just one passed in directly.
include is the same rule read the other way: a whitelist of key names
applied at every depth, not a selection of top-level fields. A nesting
key must therefore be listed too, or the branch holding the value is
dropped - jsonable_encoder(outer, include={"a"}) gives {"a": {}},
while include={"a", "b"} keeps a's b. This differs from Pydantic's
model_dump(include=...), which selects fields at one level; pass the
nested key names when you want them.
Raises ValueError on a self-referential object graph (a container
that transitively contains itself) instead of recursing until the
stack overflows. Detection is by id(); the per-call _seen set
is internal and should not be passed by callers.
custom_encoder is an optional {type: fn} mapping consulted before
every built-in rule at every depth: the exact type(obj) wins, else
the entries are scanned in insertion order returning the first
isinstance match. Because it runs first it can override container and
model handling as well as leaf scalars. Types registered process-wide
via register_encoder are consulted later (after the exact-type fast
paths) and cover subclasses through an MRO walk.
Usage::
data = jsonable_encoder(my_pydantic_model, exclude={"password"})
Register a process-level JSON encoder for type_ and its subclasses.
encoder receives one instance and must return a JSON-able value
(str/int/float/bool/None or a list/dict of such). It is consulted by
jsonable_encoder after the exact-type fast paths, resolved via an MRO
walk so subclasses of type_ are covered too. Registering a type that
already has a built-in handler overrides that handler for the type and
its subclasses.
Usage::
register_encoder(MyId, lambda v: v.hex)
Remove a previously registered encoder for type_.
No-op if type_ was never registered.
Base class for JSON serialisation providers.
Subclass to plug in an alternative serialiser, then point the app at it
via app.json (an instance) or app.json_provider_class (a class,
instantiated lazily on first access).
Usage::
class MyJSONProvider(JSONProvider):
def dumps(self, obj, **kwargs):
return my_lib.dumps(obj).encode()
def loads(self, data):
return my_lib.loads(data)
app.json_provider_class = MyJSONProvider
Serialise obj to JSON bytes. Subclasses override.
Returns bytes (not str) so callers can write directly to a
response body without re-encoding. The kwargs catch-all is
provider-specific (e.g. indent=2, sort_keys=True).
Bases: JSONProvider
orjson-backed provider — Veloce's default.
Honours two app.config flags so the existing JSON_SORT_KEYS /
JSONIFY_PRETTYPRINT_REGULAR toggles keep working without callers
needing to subclass.
Build the orjson option bitmask from an app config mapping.
Reads the JSON_SORT_KEYS and JSONIFY_PRETTYPRINT_REGULAR flags.
Shared by DefaultJSONProvider and helpers.jsonify so the two
paths cannot drift. Returns 0 when cfg is None.
Generate OpenAPI 3.1 schema from the app's registered routes.
setup_openapi_routes(app: Any, openapi_url: str = '/openapi.json', docs_url: str | None = '/docs', redoc_url: str | None = '/redoc') -> None
Register OpenAPI schema and documentation routes.
docs_url / redoc_url of None disable the Swagger UI / ReDoc UI
respectively - the JSON schema route is still registered, so tooling
can consume the schema without a public interactive explorer.