fastapi-rfc9457 0.1.0__py3-none-any.whl

fastapi_rfc9457/__init__.py

@@ -0,0 +1,54 @@
+"""fastapi-rfc9457 — typed RFC 9457 Problem Details for FastAPI & Pydantic v2."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .builtins import (
+    BadRequest,
+    Conflict,
+    Forbidden,
+    InternalServerError,
+    InvalidParam,
+    NotAuthenticated,
+    NotFound,
+    TooManyRequests,
+    UnprocessableContent,
+    ValidationProblem,
+)
+from .client import httpx_raise_hook, parse_problem, raise_for_problem
+from .docs import get_problem_docs_router
+from .integration import add_problem_handlers, problem_details_lifespan
+from .models import PROBLEM_MEDIA_TYPE, ProblemDetail
+from .openapi import problems
+from .problem import Problem, ProblemError
+
+try:
+    __version__ = version("fastapi-rfc9457")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = [
+    "PROBLEM_MEDIA_TYPE",
+    "BadRequest",
+    "Conflict",
+    "Forbidden",
+    "InternalServerError",
+    "InvalidParam",
+    "NotAuthenticated",
+    "NotFound",
+    "Problem",
+    "ProblemDetail",
+    "ProblemError",
+    "TooManyRequests",
+    "UnprocessableContent",
+    "ValidationProblem",
+    "__version__",
+    "add_problem_handlers",
+    "get_problem_docs_router",
+    "httpx_raise_hook",
+    "parse_problem",
+    "problem_details_lifespan",
+    "problems",
+    "raise_for_problem",
+]

fastapi_rfc9457/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

fastapi_rfc9457/builtins.py

@@ -0,0 +1,101 @@
+"""Ready-to-use built-in problem types and the structured-validation types."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from .problem import Problem
+
+
+class BadRequest(Problem):
+    """The request was malformed."""
+
+    title = "Bad Request"
+    status = 400
+
+
+class NotAuthenticated(Problem):
+    """Authentication is required and has failed or not been provided."""
+
+    title = "Unauthorized"
+    status = 401
+
+
+class Forbidden(Problem):
+    """You do not have permission to access this resource."""
+
+    title = "Forbidden"
+    status = 403
+
+
+class NotFound(Problem):
+    """The requested resource was not found."""
+
+    title = "Not Found"
+    status = 404
+
+
+class Conflict(Problem):
+    """The request conflicts with the current state of the resource."""
+
+    title = "Conflict"
+    status = 409
+
+
+class UnprocessableContent(Problem):
+    """The request was well-formed but could not be processed."""
+
+    title = "Unprocessable Content"
+    status = 422
+
+
+class TooManyRequests(Problem):
+    """You have sent too many requests in a given amount of time."""
+
+    title = "Too Many Requests"
+    status = 429
+
+
+class InternalServerError(Problem):
+    """The server encountered an unexpected condition."""
+
+    title = "Internal Server Error"
+    status = 500
+
+
+class InvalidParam(BaseModel):
+    """One field-level validation failure (RFC 9457 extension member).
+
+    Attributes
+    ----------
+    loc : list[str | int]
+        Faithful FastAPI location, e.g. ``["body", 0, "task_name"]`` — the list
+        index is preserved (why we use ``loc`` rather than RFC 7807's ``name``).
+        We deliberately omit a JSON Pointer rendering: ``loc`` already carries
+        strictly more (it keeps int indices distinct from string keys and avoids
+        the ``/``-escaping ambiguity a flat pointer would introduce), and a
+        location-class-prefixed pointer like ``/query/limit`` does not point into
+        any real request document.
+    detail : str
+        The pydantic error message.
+    type : str
+        The pydantic error code, e.g. ``"missing"``.
+    input : Any
+        The offending value; populated only when ``strip_debug`` is False.
+    """
+
+    loc: list[str | int]
+    detail: str
+    type: str
+    input: Any = None
+
+
+class ValidationProblem(Problem):
+    """The request failed validation."""
+
+    type = "/problems/validation"
+    title = "Unprocessable Content"
+    status = 422
+    errors: list[InvalidParam]

fastapi_rfc9457/client.py

@@ -0,0 +1,82 @@
+"""Client-side parsing of ``application/problem+json`` back into typed problems."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .models import PROBLEM_MEDIA_TYPE, ProblemDetail
+from .problem import Problem, ProblemError, extension_fields, iter_problem_types
+
+
+def _coerce(source: Any) -> dict[str, Any]:
+    if isinstance(source, dict):
+        return source
+    if isinstance(source, (bytes, bytearray, str)):
+        return json.loads(source)
+    if hasattr(source, "json"):  # httpx.Response / requests.Response
+        return source.json()
+    raise TypeError(f"Cannot parse a problem from {type(source)!r}")
+
+
+def parse_problem(source: Any) -> ProblemDetail | Problem:
+    """Parse a problem document into a typed ``Problem`` or generic ``ProblemDetail``.
+
+    Parameters
+    ----------
+    source : Any
+        A response object (with ``.json()``), a ``dict``, ``bytes``, or ``str``.
+
+    Returns
+    -------
+    ProblemDetail | Problem
+        The registered ``Problem`` subclass (extension members restored typed)
+        when ``type`` is known, otherwise a generic ``ProblemDetail``.
+    """
+    detail = ProblemDetail.model_validate(_coerce(source))
+    cls = next((c for c in iter_problem_types() if c.type == detail.type), None)
+    if cls is None:
+        return detail
+    extensions = {
+        name: getattr(detail, name) for name in extension_fields(cls) if hasattr(detail, name)
+    }
+    return cls(detail=detail.detail, instance=detail.instance, **extensions)  # type: ignore[call-arg]
+
+
+def _content_type(response: Any) -> str:
+    headers = getattr(response, "headers", {})
+    return headers.get("content-type", "") if hasattr(headers, "get") else ""
+
+
+def raise_for_problem(response: Any) -> None:
+    """Raise the mapped ``Problem`` / ``ProblemError`` if this is a problem response.
+
+    Parameters
+    ----------
+    response : Any
+        A response object with ``.headers`` and ``.json()``.
+    """
+    if PROBLEM_MEDIA_TYPE not in _content_type(response):
+        return
+    parsed = parse_problem(response)
+    if isinstance(parsed, Problem):
+        raise parsed
+    raise ProblemError(parsed)
+
+
+def httpx_raise_hook():
+    """Return an httpx ``response`` event hook that auto-raises on problem responses.
+
+    Returns
+    -------
+    Callable
+        Use as ``httpx.Client(event_hooks={"response": [httpx_raise_hook()]})``.
+    """
+
+    def hook(response: Any) -> None:
+        if PROBLEM_MEDIA_TYPE in _content_type(response):
+            if hasattr(response, "read"):
+                response.read()
+            raise_for_problem(response)
+
+    return hook

fastapi_rfc9457/docs.py

@@ -0,0 +1,144 @@
+"""Dereferenceable type-doc router, mounted explicitly by the user."""
+
+from __future__ import annotations
+
+import html
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+from starlette.responses import Response
+
+from .builtins import InternalServerError, ValidationProblem
+from .openapi import route_problem_types
+from .problem import Problem, extension_fields
+
+_HTML = """<!doctype html><meta charset="utf-8">
+<title>{title}</title>
+<main style="font-family:system-ui;max-width:48rem;margin:3rem auto;line-height:1.6">
+<h1>{title} <small style="color:#888">{status}</small></h1>
+<p><code>{type}</code></p>
+<p>{description}</p>
+<h2>Extension members</h2>
+<ul>{members}</ul>
+</main>"""
+
+
+def _format_type(typ: Any) -> str:
+    """Render a type annotation as a short, readable name.
+
+    Plain classes use their bare ``__name__`` (``int`` rather than the repr
+    ``<class 'int'>``); parameterized generics fall back to ``str`` (``list[str]``).
+
+    Parameters
+    ----------
+    typ : Any
+        A resolved type annotation.
+
+    Returns
+    -------
+    str
+        A human-readable rendering of the annotation.
+    """
+    return typ.__name__ if isinstance(typ, type) else str(typ)
+
+
+def _payload(cls: type[Problem]) -> dict[str, Any]:
+    return {
+        "type": cls.type,
+        "title": cls.title,
+        "status": cls.status,
+        "description": (cls.__doc__ or "").strip(),
+        "extensions": {name: _format_type(typ) for name, typ in extension_fields(cls).items()},
+    }
+
+
+def _slug(cls: type[Problem]) -> str:
+    return (cls.type or "").rsplit("/", 1)[-1]
+
+
+def _render(cls: type[Problem], request: Request) -> Response:
+    data = _payload(cls)
+    if "text/html" in request.headers.get("accept", ""):
+        members = "".join(
+            f"<li><code>{html.escape(name)}</code>: {html.escape(typ)}</li>"
+            for name, typ in data["extensions"].items()
+        )
+        escaped = {k: html.escape(str(v)) for k, v in data.items() if k != "extensions"}
+        return HTMLResponse(_HTML.format(members=members, **escaped))
+    return JSONResponse(data)
+
+
+def _documented_types(app: Any) -> list[type[Problem]]:
+    """Types whose doc pages this app serves: those on its routes plus the two
+    builtins ``add_problem_handlers`` always emits (validation 422, unhandled 500)."""
+    seen = {cls.type: cls for cls in route_problem_types(app)}
+    for cls in (ValidationProblem, InternalServerError):
+        seen.setdefault(cls.type, cls)
+    return list(seen.values())
+
+
+def get_problem_docs_router(*types: type[Problem]) -> APIRouter:
+    """Return a router serving one doc page per problem type.
+
+    Two modes:
+
+    * **Route-derived (no arguments).** Serves a page for every problem type the
+      app declares via ``responses=problems(...)`` (plus the always-on validation
+      and internal-error types), resolved from the request's app at call time.
+      Adding a new type to a route is the only change needed — nothing to restate
+      here.
+    * **Explicit.** Pass specific types to publish exactly those pages (useful for
+      a standalone docs app with no routes raising them).
+
+    Parameters
+    ----------
+    *types : type[Problem]
+        The types to document, or none to derive them from the app's routes.
+
+    Returns
+    -------
+    APIRouter
+        Mount it yourself with ``app.include_router(..., prefix=..., tags=...)``;
+        point your ``type`` URIs at the chosen prefix.
+    """
+    router = APIRouter()
+
+    if not types:
+
+        async def endpoint(slug: str, request: Request) -> Response:
+            available = {_slug(cls): cls for cls in _documented_types(request.app)}
+            match = available.get(slug)
+            if match is None:
+                raise HTTPException(
+                    status_code=404, detail=f"No problem type documented at {slug!r}"
+                )
+            return _render(match, request)
+
+        router.add_api_route(
+            "/{slug}",
+            endpoint,
+            methods=["GET"],
+            name="problem-doc",
+            summary="Problem type documentation",
+        )
+        return router
+
+    for cls in types:
+        slug = _slug(cls)
+
+        def make_endpoint(problem_cls: type[Problem]):
+            async def endpoint(request: Request) -> Response:
+                return _render(problem_cls, request)
+
+            return endpoint
+
+        router.add_api_route(
+            f"/{slug}",
+            make_endpoint(cls),
+            methods=["GET"],
+            name=f"problem-doc-{slug}",
+            summary=f"{cls.title} ({cls.status})",
+        )
+
+    return router

fastapi_rfc9457/handlers.py

@@ -0,0 +1,138 @@
+"""The four exception handlers and the per-request wire-model builder."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from http import HTTPStatus
+from typing import cast
+
+from fastapi import Request
+from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.responses import Response
+
+from .builtins import InternalServerError, InvalidParam, ValidationProblem
+from .models import PROBLEM_MEDIA_TYPE, ProblemDetail
+from .problem import Problem, extension_fields
+
+Handler = Callable[[Request, Exception], Awaitable[Response]]
+
+
+def build_wire(problem: Problem, *, instance: str | None) -> ProblemDetail:
+    """Materialize a fresh wire model from a carried problem (never mutates it).
+
+    Parameters
+    ----------
+    problem : Problem
+        The raised problem instance (read-only input).
+    instance : str | None
+        Resolved ``instance`` to use when the problem didn't set one.
+
+    Returns
+    -------
+    ProblemDetail
+        A brand-new wire model for this request.
+    """
+    cls = type(problem)
+    extensions = {name: getattr(problem, name) for name in extension_fields(cls)}
+    return ProblemDetail(
+        type=cls.type or "about:blank",
+        title=cls.title,
+        status=cls.status,
+        detail=problem.detail,
+        instance=problem.instance if problem.instance is not None else instance,
+        **extensions,
+    )
+
+
+def _respond(detail: ProblemDetail) -> Response:
+    return Response(
+        content=detail.model_dump_json(exclude_none=True),
+        status_code=detail.status,
+        media_type=PROBLEM_MEDIA_TYPE,
+    )
+
+
+def make_handlers(*, strip_debug: bool, instance_from_request: bool) -> dict[type, Handler]:
+    """Build the exception-type -> handler mapping for ``add_exception_handler``.
+
+    Parameters
+    ----------
+    strip_debug : bool
+        Redact ``detail`` on 500s and the offending ``input`` on 422s.
+    instance_from_request : bool
+        Auto-fill ``instance`` from the request path when unset.
+
+    Returns
+    -------
+    dict[type, Handler]
+        Mapping suitable for iterating into ``app.add_exception_handler``.
+    """
+
+    def _instance(request: Request) -> str | None:
+        return request.url.path if instance_from_request else None
+
+    async def problem_handler(request: Request, exc: Problem) -> Response:
+        return _respond(build_wire(exc, instance=_instance(request)))
+
+    async def validation_handler(request: Request, exc: RequestValidationError) -> Response:
+        params: list[InvalidParam] = []
+        for err in exc.errors():
+            loc = list(err["loc"])
+            param = InvalidParam(
+                loc=loc,
+                detail=err["msg"],
+                type=err["type"],
+                input=None if strip_debug or "input" not in err else jsonable_encoder(err["input"]),
+            )
+            params.append(param)
+        n = len(params)
+        wire = ProblemDetail.model_validate(
+            {
+                "type": ValidationProblem.type or "about:blank",
+                "title": ValidationProblem.title,
+                "status": ValidationProblem.status,
+                "detail": f"Request validation failed ({n} error{'' if n == 1 else 's'}).",
+                "instance": _instance(request),
+                "errors": [p.model_dump(exclude_none=True) for p in params],
+            }
+        )
+        return _respond(wire)
+
+    async def http_handler(request: Request, exc: StarletteHTTPException) -> Response:
+        try:
+            title = HTTPStatus(exc.status_code).phrase
+        except ValueError:
+            title = "Error"
+        wire = ProblemDetail(
+            type="about:blank",
+            title=title,
+            status=exc.status_code,
+            detail=exc.detail if isinstance(exc.detail, str) else None,
+            instance=_instance(request),
+        )
+        response = _respond(wire)
+        if exc.headers:
+            response.headers.update(exc.headers)
+        return response
+
+    async def unhandled_handler(request: Request, exc: Exception) -> Response:
+        wire = ProblemDetail(
+            type=InternalServerError.type or "about:blank",
+            title=InternalServerError.title,
+            status=InternalServerError.status,
+            detail=None if strip_debug else f"{type(exc).__name__}: {exc}",
+            instance=_instance(request),
+        )
+        return _respond(wire)
+
+    return cast(
+        dict[type, Handler],
+        {
+            Problem: problem_handler,
+            RequestValidationError: validation_handler,
+            StarletteHTTPException: http_handler,
+            Exception: unhandled_handler,
+        },
+    )

fastapi_rfc9457/integration.py

@@ -0,0 +1,76 @@
+"""Explicit, named wiring: handlers + OpenAPI registration."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from .handlers import make_handlers
+from .openapi import register_problem_components
+from .problem import iter_problem_types
+
+_INSTALLED_FLAG = "_fastapi_rfc9457_installed"
+
+
+def add_problem_handlers(
+    app: FastAPI,
+    *,
+    strip_debug: bool = False,
+    instance_from_request: bool = True,
+) -> None:
+    """Register the four problem handlers and the OpenAPI component registration.
+
+    Does **not** mount the docs router (mount it explicitly). Idempotent: a second
+    call warns and returns.
+
+    Parameters
+    ----------
+    app : FastAPI
+        The application to wire.
+    strip_debug : bool, optional
+        Redact ``detail`` on 500s and the offending ``input`` on 422s, by default
+        False.
+    instance_from_request : bool, optional
+        Auto-fill ``instance`` from the request path when unset, by default True.
+    """
+    if getattr(app.state, _INSTALLED_FLAG, False):
+        warnings.warn(
+            "add_problem_handlers was called more than once on this app; ignoring the repeat.",
+            stacklevel=2,
+        )
+        return
+
+    handlers = make_handlers(strip_debug=strip_debug, instance_from_request=instance_from_request)
+    for exc_type, handler in handlers.items():
+        app.add_exception_handler(exc_type, handler)
+
+    register_problem_components(app)
+    setattr(app.state, _INSTALLED_FLAG, True)
+
+
+@asynccontextmanager
+async def problem_details_lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Composable lifespan: validate every defined problem type on startup.
+
+    Nest this inside your own lifespan (user lifespan outer, ours inner). It
+    fails fast if any defined problem type is missing ``title`` or ``status``.
+    Duplicate type URIs are rejected later, when the OpenAPI schema is built.
+
+    Parameters
+    ----------
+    app : FastAPI
+        The application (unused today; reserved for app-metadata binding).
+
+    Yields
+    ------
+    None
+    """
+    for cls in iter_problem_types():
+        if not getattr(cls, "title", None):
+            raise RuntimeError(f"Problem type {cls.__name__} ({cls.type!r}) is missing a title")
+        if not getattr(cls, "status", None):
+            raise RuntimeError(f"Problem type {cls.__name__} ({cls.type!r}) is missing a status")
+    yield

fastapi_rfc9457/models.py

@@ -0,0 +1,36 @@
+"""The canonical RFC 9457 wire model."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+PROBLEM_MEDIA_TYPE = "application/problem+json"
+
+
+class ProblemDetail(BaseModel):
+    """Serialized RFC 9457 problem document.
+
+    Unknown extension members are carried verbatim (``extra="allow"``), so this
+    one model is both the emitted wire shape and the generic client-parse result.
+
+    Attributes
+    ----------
+    type : str
+        Problem-type URI reference. Defaults to ``"about:blank"`` per RFC 9457.
+    title : str
+        Short, human-readable summary of the problem type.
+    status : int
+        HTTP status code generated for this occurrence.
+    detail : str | None
+        Human-readable explanation specific to this occurrence.
+    instance : str | None
+        URI reference identifying this specific occurrence.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    type: str = "about:blank"
+    title: str
+    status: int
+    detail: str | None = None
+    instance: str | None = None

fastapi_rfc9457/openapi.py

@@ -0,0 +1,401 @@
+"""OpenAPI integration: the ``problems()`` responses helper and component wiring.
+
+The design mirrors ``fastapi-pagination``'s ``add_pagination(app)``: routes carry
+real model objects (via FastAPI's native ``responses={status: {"model": ...}}``),
+and a single ``app.openapi`` wrap recovers them by walking the routes. FastAPI
+auto-registers the component schemas for us; the wrap only normalizes each
+response to ``application/problem+json`` (FastAPI emits models under
+``application/json``), converts unions to ``oneOf``, rewrites the auto-generated
+422, and validates type-URI uniqueness at build time. No global registry.
+"""
+
+from __future__ import annotations
+
+import json
+import types
+from functools import reduce
+from operator import or_
+from typing import Any, Literal, Union, get_args, get_origin
+
+from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
+from fastapi.routing import APIRoute
+from pydantic import BaseModel, ConfigDict, create_model
+
+from .builtins import ValidationProblem
+from .models import PROBLEM_MEDIA_TYPE, ProblemDetail
+from .problem import Problem, extension_fields
+
+_REF_TEMPLATE = "#/components/schemas/{model}"
+_HTTP_VALIDATION_ERROR = _REF_TEMPLATE.format(model="HTTPValidationError")
+
+# Memoized per-type wire models, keyed by source class identity. This is a cache
+# for correct/stable component naming (one component per type, not per route) —
+# not a discovery registry: what gets documented is decided by the routes.
+_WIRE_CACHE: dict[type[Problem], type[BaseModel]] = {}
+
+
+class _WireBase(ProblemDetail):
+    """Closed (``extra='forbid'``) variant of :class:`ProblemDetail` for docs.
+
+    The open base carries unknown members for client parsing; a *documented*
+    problem type has a known, closed set of extensions, so its schema forbids
+    extras (no ``additionalProperties: true`` noise in the rendered docs).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+
+def _literal(value: object) -> Any:
+    """Build a single-value ``Literal`` from a runtime value (inherently dynamic)."""
+    return Literal[value]  # type: ignore[valid-type]
+
+
+def _union(models: list[type[BaseModel]]) -> Any:
+    """Combine 2+ models into a single ``X | Y`` union type (for a shared status)."""
+    return reduce(or_, models)
+
+
+def _wire_model(cls: type[Problem]) -> type[BaseModel]:
+    """Build (or reuse) the per-type wire model: closed, const ``type``/``status``.
+
+    Parameters
+    ----------
+    cls : type[Problem]
+        The authored problem type.
+
+    Returns
+    -------
+    type[BaseModel]
+        A Pydantic model named ``cls.__name__`` whose ``type`` and ``status`` are
+        pinned to the class's values, carrying ``__problem_source__`` for recovery.
+    """
+    cached = _WIRE_CACHE.get(cls)
+    if cached is not None:
+        return cached
+    fields: dict[str, Any] = {name: (typ, ...) for name, typ in extension_fields(cls).items()}
+    model = create_model(  # type: ignore[call-overload]
+        cls.__name__,
+        __base__=_WireBase,
+        type=(_literal(cls.type), cls.type),
+        status=(_literal(cls.status), cls.status),
+        title=(str, cls.title),
+        **fields,
+    )
+    model.__problem_source__ = cls  # type: ignore[attr-defined]
+    _WIRE_CACHE[cls] = model
+    return model
+
+
+def problems(*types_: type[Problem]) -> dict[int | str, dict[str, Any]]:
+    """Build a ``responses=`` mapping for the given problem types.
+
+    Types sharing a status are merged into one response. The result spreads into
+    any ``responses=``. The actual ``application/problem+json`` media type and
+    ``oneOf`` shaping are applied at OpenAPI build time by
+    :func:`register_problem_components` (wired through :func:`add_problem_handlers`).
+
+    Parameters
+    ----------
+    *types_ : type[Problem]
+        The problem types a route can raise.
+
+    Returns
+    -------
+    dict[int | str, dict[str, Any]]
+        A ``responses=`` mapping keyed by status code.
+    """
+    grouped: dict[int, list[type[Problem]]] = {}
+    for problem_type in types_:
+        grouped.setdefault(problem_type.status, []).append(problem_type)
+
+    responses: dict[int | str, dict[str, Any]] = {}
+    for status, group in grouped.items():
+        wires = [_wire_model(t) for t in group]
+        model: Any = wires[0] if len(wires) == 1 else _union(wires)
+        descriptions = [(t.__doc__ or t.title).strip() for t in group]
+        responses[status] = {"model": model, "description": " / ".join(descriptions)}
+    return responses
+
+
+def _problem_wire_members(model: Any) -> list[type[BaseModel]] | None:
+    """Return the problem wire models behind a response ``model``, or ``None``.
+
+    Handles both a single wire model and a ``Union`` of them. Returns ``None`` for
+    anything that isn't (entirely) our wire models, so user responses are untouched.
+    """
+    if model is None:
+        return None
+    is_union = get_origin(model) in (Union, types.UnionType)
+    members = list(get_args(model)) if is_union else [model]
+    if members and all(getattr(m, "__problem_source__", None) is not None for m in members):
+        return members
+    return None
+
+
+def route_problem_types(app: FastAPI) -> list[type[Problem]]:
+    """Return the problem types an app declares on its routes, in first-seen order.
+
+    Recovers the authored :class:`Problem` classes from each route's
+    ``responses=problems(...)`` (the same recovery the OpenAPI wrap performs), so
+    callers never restate the type list. Deduplicated by class identity.
+
+    Parameters
+    ----------
+    app : FastAPI
+        The application to inspect.
+
+    Returns
+    -------
+    list[type[Problem]]
+        Every problem type referenced by the app's route responses.
+    """
+    seen: dict[type[Problem], None] = {}
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+        for entry in route.responses.values():
+            members = _problem_wire_members(entry.get("model"))
+            if members is None:
+                continue
+            for member in members:
+                seen.setdefault(member.__problem_source__, None)  # type: ignore[attr-defined]
+    return list(seen)
+
+
+def _ref_schema(
+    members: list[type[BaseModel]], seen_uris: dict[str, type[Problem]]
+) -> dict[str, Any]:
+    """Build the ``$ref``/``oneOf`` schema for a response, checking URI uniqueness."""
+    refs: list[dict[str, Any]] = []
+    for member in members:
+        source: type[Problem] = member.__problem_source__  # type: ignore[attr-defined]
+        uri = source.type or "about:blank"
+        existing = seen_uris.get(uri)
+        if existing is not None and existing is not source:
+            raise ValueError(
+                f"Duplicate problem type URI {uri!r}: {existing.__name__} and "
+                f"{source.__name__}. Give each Problem subclass a distinct `type`."
+            )
+        seen_uris[uri] = source
+        refs.append({"$ref": _REF_TEMPLATE.format(model=member.__name__)})
+    return refs[0] if len(refs) == 1 else {"oneOf": refs}
+
+
+_JSON_SAMPLES: dict[str | None, Any] = {
+    "string": "string",
+    "integer": 0,
+    "number": 0.0,
+    "boolean": True,
+}
+
+
+def _sample_value(prop: dict[str, Any], defs: dict[str, Any]) -> Any:
+    """Produce a representative sample value for one JSON-Schema property.
+
+    Pinned values win (``const`` then ``default``); otherwise a placeholder is
+    chosen by JSON type. ``$ref`` is resolved through ``defs`` and ``anyOf``/
+    ``oneOf`` follow the first non-null branch, mirroring the concrete shape a
+    client would send.
+
+    Parameters
+    ----------
+    prop : dict[str, Any]
+        A JSON-Schema property subschema.
+    defs : dict[str, Any]
+        The owning schema's ``$defs`` map, for resolving ``$ref``.
+
+    Returns
+    -------
+    Any
+        A JSON-serializable sample value.
+    """
+    if "const" in prop:
+        return prop["const"]
+    if "default" in prop:
+        return prop["default"]
+    if "$ref" in prop:
+        return _sample_value(defs.get(prop["$ref"].rsplit("/", 1)[-1], {}), defs)
+    for branch_key in ("anyOf", "oneOf"):
+        branches = [b for b in prop.get(branch_key, ()) if b.get("type") != "null"]
+        if branches:
+            return _sample_value(branches[0], defs)
+    json_type = prop.get("type")
+    if json_type == "array":
+        items = prop.get("items")
+        return [_sample_value(items, defs)] if items else []
+    if json_type == "object":
+        return {n: _sample_value(s, defs) for n, s in prop.get("properties", {}).items()}
+    return _JSON_SAMPLES.get(json_type)
+
+
+def _example_for(model: type[BaseModel]) -> dict[str, Any]:
+    """Build one representative example payload for a problem wire model.
+
+    Includes the identity members the type fixes (the ``type``/``status`` consts
+    and the ``title`` default) plus every required extension member, each filled
+    with a JSON-type-appropriate sample. Optional members (``detail``,
+    ``instance``) are omitted — they carry no canonical per-type example value.
+
+    Parameters
+    ----------
+    model : type[BaseModel]
+        A problem wire model (from :func:`_wire_model`).
+
+    Returns
+    -------
+    dict[str, Any]
+        A JSON object suitable as an OpenAPI example ``value``.
+    """
+    schema = model.model_json_schema(ref_template=_REF_TEMPLATE)
+    defs = schema.get("$defs", {})
+    required = set(schema.get("required", ()))
+    example: dict[str, Any] = {}
+    for name, prop in schema.get("properties", {}).items():
+        if name in required or "const" in prop or prop.get("default") is not None:
+            example[name] = _sample_value(prop, defs)
+    return example
+
+
+def _problem_examples(members: list[type[BaseModel]]) -> dict[str, Any]:
+    """Build a named OpenAPI ``examples`` map, one entry per ``oneOf`` member.
+
+    Swagger UI synthesizes only a single example from a ``oneOf`` schema (the
+    first branch), hiding every sibling. Explicit named examples make it render
+    a dropdown with one labelled payload per problem type.
+
+    Parameters
+    ----------
+    members : list[type[BaseModel]]
+        The problem wire models behind a shared-status response.
+
+    Returns
+    -------
+    dict[str, Any]
+        An OpenAPI ``examples`` map keyed by wire-model name.
+    """
+    examples: dict[str, Any] = {}
+    for member in members:
+        source: type[Problem] = member.__problem_source__  # type: ignore[attr-defined]
+        examples[member.__name__] = {
+            "summary": f"{source.title} ({source.status})",
+            "value": _example_for(member),
+        }
+    return examples
+
+
+def _ensure_component(components: dict[str, Any], model: type[BaseModel]) -> None:
+    """Add ``model``'s JSON schema (lifting nested ``$defs``) if not already present."""
+    schema = model.model_json_schema(ref_template=_REF_TEMPLATE)
+    defs = schema.pop("$defs", {})
+    components.setdefault(model.__name__, schema)
+    for name, sub_schema in defs.items():
+        components.setdefault(name, sub_schema)
+
+
+def _rewrite_validation_responses(paths: dict[str, Any], components: dict[str, Any]) -> None:
+    """Rewrite FastAPI's auto-generated 422 to ``application/problem+json``.
+
+    The runtime already emits ``ValidationProblem`` as ``application/problem+json``;
+    this aligns the *documentation* (RFC 9457 §3) for every route FastAPI gave a
+    default ``HTTPValidationError`` 422.
+    """
+    rewrote = False
+    for path_item in paths.values():
+        if not isinstance(path_item, dict):
+            continue
+        for operation in path_item.values():
+            if not isinstance(operation, dict) or "responses" not in operation:
+                continue
+            response = operation["responses"].get("422")
+            if not isinstance(response, dict):
+                continue
+            schema = response.get("content", {}).get("application/json", {}).get("schema", {})
+            if schema.get("$ref") == _HTTP_VALIDATION_ERROR:
+                response["content"] = {
+                    PROBLEM_MEDIA_TYPE: {
+                        "schema": {"$ref": _REF_TEMPLATE.format(model="ValidationProblem")}
+                    }
+                }
+                rewrote = True
+    if rewrote:
+        _ensure_component(components, _wire_model(ValidationProblem))
+
+
+def _prune_unreferenced(schema: dict[str, Any], names: tuple[str, ...]) -> None:
+    """Drop named components no longer pointed at by any ``$ref`` (cleanup pass)."""
+    schemas = schema.get("components", {}).get("schemas", {})
+    for name in names:
+        # Re-serialize each pass: removing one component frees refs held only by it.
+        if f'"{_REF_TEMPLATE.format(model=name)}"' not in json.dumps(schema):
+            schemas.pop(name, None)
+
+
+def register_problem_components(app: FastAPI) -> None:
+    """Wrap ``app.openapi`` to normalize problem responses and components.
+
+    The FastAPI-endorsed *Extending OpenAPI* pattern: idempotent and lazy, so it
+    sees every route regardless of when it is called. It recovers the problem
+    types each route declares (from the response models), rewrites them to
+    ``application/problem+json`` (``oneOf`` for a shared status), aligns the
+    auto-generated 422, and raises if two types share a ``type`` URI.
+
+    Parameters
+    ----------
+    app : FastAPI
+        The application whose ``openapi`` callable is wrapped.
+    """
+
+    def custom_openapi() -> dict[str, Any]:
+        if app.openapi_schema:
+            return app.openapi_schema
+        schema = get_openapi(
+            title=app.title,
+            version=app.version,
+            openapi_version=app.openapi_version,
+            summary=app.summary,
+            description=app.description,
+            routes=app.routes,
+            webhooks=app.webhooks.routes,
+            tags=app.openapi_tags,
+            servers=app.servers,
+            terms_of_service=app.terms_of_service,
+            contact=app.contact,
+            license_info=app.license_info,
+        )
+        paths: dict[str, Any] = schema.get("paths", {})
+        components: dict[str, Any] = schema.setdefault("components", {}).setdefault("schemas", {})
+
+        seen_uris: dict[str, type[Problem]] = {}
+        for route in app.routes:
+            if not isinstance(route, APIRoute) or not route.methods:
+                continue
+            path_item = paths.get(route.path_format)
+            if path_item is None:
+                continue
+            for status, entry in route.responses.items():
+                members = _problem_wire_members(entry.get("model"))
+                if members is None:
+                    continue
+                content_schema = _ref_schema(members, seen_uris)
+                media: dict[str, Any] = {"schema": content_schema}
+                if len(members) > 1:
+                    # Swagger UI samples only the first oneOf branch; name an
+                    # example per member so it offers a per-type dropdown.
+                    media["examples"] = _problem_examples(members)
+                for method in route.methods:
+                    operation = path_item.get(method.lower())
+                    if not isinstance(operation, dict):
+                        continue
+                    response = operation.get("responses", {}).get(str(status))
+                    if response is not None:
+                        response["content"] = {PROBLEM_MEDIA_TYPE: media}
+
+        _rewrite_validation_responses(paths, components)
+        _ensure_component(components, ProblemDetail)  # canonical open base shape
+        _prune_unreferenced(schema, ("HTTPValidationError", "ValidationError"))
+
+        app.openapi_schema = schema
+        return schema
+
+    app.openapi = custom_openapi  # type: ignore[method-assign]

fastapi_rfc9457/problem.py

@@ -0,0 +1,155 @@
+"""The ``Problem`` authoring surface: a frozen Pydantic dataclass + ``Exception``."""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+from collections.abc import Iterator
+from typing import ClassVar, dataclass_transform, get_type_hints
+
+import pydantic
+
+from .models import ProblemDetail
+
+_STANDARD_FIELDS = frozenset({"detail", "instance"})
+
+
+def _derive_type(name: str) -> str:
+    """Derive a kebab-case type id from a class name.
+
+    A trailing ``Problem`` or ``Error`` is stripped, then the CamelCase name is
+    lower-kebab-cased. ``OutOfCredit`` -> ``"out-of-credit"``.
+
+    Parameters
+    ----------
+    name : str
+        The class ``__name__``.
+
+    Returns
+    -------
+    str
+        The derived relative type-URI reference (RFC 9457 §3.1.1 permits these).
+
+    Notes
+    -----
+    Derivation is lossy for acronym-heavy names (``HTTPError`` -> ``"http"``);
+    set an explicit ``type`` ClassVar when the derived id would be ambiguous.
+    """
+    base = re.sub(r"(Problem|Error)$", "", name) or name
+    step = re.sub(r"(.)([A-Z][a-z]+)", r"\1-\2", base)
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", step).lower()
+
+
+def extension_fields(cls: type) -> dict[str, type]:
+    """Return the typed extension members of a problem class.
+
+    Annotations are resolved with :func:`typing.get_type_hints` so that string
+    annotations (PEP 563 / ``from __future__ import annotations``) come back as
+    real types rather than strings.
+
+    Parameters
+    ----------
+    cls : type
+        A ``Problem`` subclass.
+
+    Returns
+    -------
+    dict[str, type]
+        Field name -> resolved annotation, excluding the standard
+        ``detail``/``instance`` members.
+    """
+    hints = get_type_hints(cls)
+    return {
+        field.name: hints[field.name]
+        for field in dataclasses.fields(cls)
+        if field.name not in _STANDARD_FIELDS
+    }
+
+
+@dataclass_transform(kw_only_default=True, frozen_default=True)
+class _ProblemMeta(type):
+    """Metaclass that makes ``Problem`` and every subclass a frozen kw-only dataclass.
+
+    The ``@dataclass_transform`` decoration tells static checkers to treat each
+    subclass as a dataclass (so field declarations become kw-only, type-checked
+    constructor parameters); ``__new__`` applies the runtime transform.
+
+    The transform is configured ``extra="forbid"`` so an unknown constructor
+    keyword — a typo, or an attempt to pass a ``ClassVar`` constant such as
+    ``status=404`` — raises rather than being silently dropped.
+    """
+
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, object],
+        **kwargs: object,
+    ):
+        cls = super().__new__(mcs, name, bases, namespace, **kwargs)
+        config = pydantic.ConfigDict(extra="forbid")
+        return pydantic.dataclasses.dataclass(config=config, kw_only=True, frozen=True)(cls)
+
+
+class Problem(Exception, metaclass=_ProblemMeta):
+    """Base class for authored RFC 9457 problem types.
+
+    Subclasses declare ``title``/``status`` (and optionally ``type``) as plain
+    class attributes — they are ``ClassVar`` constants, not fields — and declare
+    extension members as annotated fields. Raise instances directly.
+
+    Notes
+    -----
+    No decorator is needed on subclasses: the metaclass carries the dataclass
+    machinery. Instances are frozen, so module-level constants are safe to reuse.
+    Unknown constructor keywords are rejected (``extra="forbid"``): passing a
+    ``ClassVar`` constant like ``status=404`` raises rather than being ignored.
+    """
+
+    title: ClassVar[str]
+    status: ClassVar[int]
+    type: ClassVar[str | None] = None
+    detail: str | None = None
+    instance: str | None = None
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        super().__init_subclass__(**kwargs)
+        cls.type = cls.type if cls.type is not None else _derive_type(cls.__name__)
+
+
+def iter_problem_types() -> Iterator[type[Problem]]:
+    """Yield every defined :class:`Problem` subclass, transitively.
+
+    Walks ``Problem.__subclasses__()`` (Python's own weakly-held subclass list),
+    so no explicit registry is kept: a type is "known" exactly while it is a live
+    class. Used to map an incoming ``type`` URI back to its authored class and to
+    validate the type set at startup.
+
+    Yields
+    ------
+    type[Problem]
+        Each distinct subclass, deduplicated.
+    """
+    seen: set[type[Problem]] = set()
+    stack: list[type[Problem]] = list(Problem.__subclasses__())
+    while stack:
+        cls = stack.pop()
+        if cls in seen:
+            continue
+        seen.add(cls)
+        yield cls
+        stack.extend(cls.__subclasses__())
+
+
+class ProblemError(Exception):
+    """Client-side fallback for a problem response whose ``type`` isn't registered.
+
+    Parameters
+    ----------
+    problem : ProblemDetail
+        The parsed wire model.
+    """
+
+    def __init__(self, problem: ProblemDetail) -> None:
+        self.problem = problem
+        super().__init__(f"{problem.status} {problem.title}")

fastapi_rfc9457-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: fastapi-rfc9457
+Version: 0.1.0
+Summary: Typed, batteries-included RFC 9457 Problem Details for FastAPI & Pydantic v2.
+Author: Fabian Zills
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.137.2
+Requires-Dist: pydantic>=2.13.4
+Provides-Extra: client
+Requires-Dist: httpx>=0.27; extra == 'client'
+Description-Content-Type: text/markdown
+
+# fastapi-rfc9457
+
+Typed, batteries-included [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html)
+"Problem Details for HTTP APIs" for FastAPI & Pydantic.
+
+Define an error once - it serializes as `application/problem+json`, documents
+itself in OpenAPI, and parses back into a typed exception on the client.
+
+```python
+from fastapi import FastAPI
+from fastapi_rfc9457 import Problem, add_problem_handlers, get_problem_docs_router, problems
+
+
+class OutOfCredit(Problem):
+    """The account does not have enough credit."""
+    type = "/problems/out-of-credit"
+    title = "Out of Credit"
+    status = 403
+    balance: int            # typed extension members, checked at the raise site
+    accounts: list[str]
+
+
+class AccountSuspended(Problem):
+    """The account is suspended and cannot be charged."""
+    type = "/problems/account-suspended"
+    title = "Account Suspended"
+    status = 403
+
+
+app = FastAPI()
+add_problem_handlers(app)                                          # handlers + problem+json OpenAPI
+app.include_router(get_problem_docs_router(), prefix="/problems")  # dereferenceable type URIs
+
+
+@app.get("/charge", responses=problems(OutOfCredit, AccountSuspended))
+async def charge() -> dict:
+    raise OutOfCredit(detail="Not enough credit.", balance=30, accounts=["/acct/12"])
+```
+
+## Accurate OpenAPI, for free
+
+One route can declare several failure modes. Distinct statuses get their own
+response; same-status problems become a `oneOf` union you flip through in
+Swagger's **Examples** dropdown — all under `application/problem+json`.
+
+![Swagger error responses with a problem+json examples dropdown](docs/img/swagger-errors.png)
+
+## Dereferenceable `type` URIs
+
+Mount the docs router and every problem `type` resolves to a live page listing
+its typed extension members.
+
+![Problem type documentation page](docs/img/doc-page.png)
+
+## Features
+
+- **Typed + validated extension members** that round-trip through serialization, OpenAPI, and the client.
+- **Accurate per-route OpenAPI** under `application/problem+json`.
+- **Structured 422** that preserves field + list-index mapping (no flattening).
+- **Client-side parsing** back into typed problems.
+
+## Install
+
+```bash
+uv add fastapi-rfc9457          # add fastapi-rfc9457[client] for the httpx hook
+```
+
+## Example
+
+```bash
+cd example && uv run uvicorn main:app --reload   # then open localhost:8000/docs
+```
+
+See [`example/`](./example) for the full runnable app, and
+[`example/client.py`](./example/client.py) for the httpx hook (`fastapi-rfc9457[client]`)
+that raises those problems back as typed exceptions on the consumer side.
+
+## Notes
+
+- Replaces FastAPI's default 422 body with `application/problem+json`.
+

fastapi_rfc9457-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+fastapi_rfc9457/__init__.py,sha256=hKww54qZTUAzn4aw_zE5zXb9xqpPx-ntAGGXZZv4ja8,1348
+fastapi_rfc9457/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+fastapi_rfc9457/builtins.py,sha256=0xXGj2UwjrzFehXZ3W1v9JUAUFihr7MlK33G4A9-nQs,2487
+fastapi_rfc9457/client.py,sha256=MBYaw_YUP9kYBs5DzZJJFJdJA8hZEPE45qkjhaBYtEw,2625
+fastapi_rfc9457/docs.py,sha256=Nssizu67w57VOE_Og2rlaaAUX62nGFgRq2vTZLFK-ek,4679
+fastapi_rfc9457/handlers.py,sha256=0QEBv8jnXv-puhaJaDjKE5yD9vi74qrCG3iXz0MaZDc,4795
+fastapi_rfc9457/integration.py,sha256=XgsfLU_talKPk8ELGrn_jzOmg1LhGxVR_Diy4SR6U6A,2485
+fastapi_rfc9457/models.py,sha256=Eow8kiCqjwBxF-An-GzJ-1jZDgdfNCW30e_4x97tZJo,1038
+fastapi_rfc9457/openapi.py,sha256=B4GfNBLvUz1cIHVIxs8WZUpEpHOC56jUhpb_UNfDaZw,15731
+fastapi_rfc9457/problem.py,sha256=y_W6pUQW_WCwSnpyiQnq_9qbCMWjKHnBFMlf9AP1wJY,5050
+fastapi_rfc9457/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_rfc9457-0.1.0.dist-info/METADATA,sha256=FUqQizujUvQycqQDMXoB0N3By1LYcWeTrEPZ5H7iC-A,3076
+fastapi_rfc9457-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fastapi_rfc9457-0.1.0.dist-info/RECORD,,

fastapi_rfc9457-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any