fastapi-rfc9457 0.1.0__tar.gz

fastapi_rfc9457-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# hatch-vcs generated
+src/fastapi_rfc9457/_version.py

fastapi_rfc9457-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,81 @@
+# 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/example/README.md

@@ -0,0 +1,52 @@
+# fastapi-rfc9457 — example app
+
+```bash
+uv run uvicorn main:app --reload   # open http://localhost:8000/docs
+```
+
+```bash
+curl -i localhost:8000/posts/999          # 404  application/problem+json
+curl -i "localhost:8000/search?limit=abc" # 422  errors[] with loc ["query","limit"]
+curl -i localhost:8000/charge             # 401  NotAuthenticated (no token)
+curl -i "localhost:8000/charge?token=x"   # 403  OutOfCredit + typed balance/accounts
+curl -s localhost:8000/problems/out-of-credit  # dereferenced type-doc page
+```
+
+`/charge` declares three problems via `problems(...)`: a 401 and a same-status
+403 `oneOf` union (`OutOfCredit` / `AccountSuspended`) — see them in `/docs`.
+
+## Consuming it with the httpx hook
+
+`fastapi-rfc9457[client]` ships an httpx event hook that turns every
+`application/problem+json` reply back into the same typed exception the server
+raised. [`client.py`](./client.py) is a runnable consumer of the server above.
+
+With the demo server running (above), in another shell from this `example/`
+directory:
+
+```bash
+uv add fastapi-rfc9457[client]   # the httpx extra
+uv run client.py                 # connects to http://localhost:8000
+```
+
+It prints:
+
+```text
+GET /posts/1   -> {'id': '1', 'title': 'Hello'}
+PostNotFound   -> Post 999 not found
+OutOfCredit    -> balance=30, accounts=['/accounts/12']
+NotAuthenticated -> Log in to charge this account.
+```
+
+The hook is synchronous (`response.read()`), so it wires onto `httpx.Client`;
+`httpx.AsyncClient` is not supported today.
+
+## Notes
+
+- This replaces FastAPI's default 422 `application/json` body with
+  `application/problem+json` carrying a structured `errors[]` extension member —
+  intended, since the goal is a uniform error surface.
+- Under `app.debug=True`, Starlette renders a traceback page *instead of*
+  invoking the 500 handler, so the `problem+json` 500 path isn't exercised in
+  debug; Starlette also re-raises the unhandled exception after the handler runs
+  (for logging). Both are expected.

fastapi_rfc9457-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastapi-rfc9457"
+description = "Typed, batteries-included RFC 9457 Problem Details for FastAPI & Pydantic v2."
+readme = "README.md"
+requires-python = ">=3.11"
+dynamic = ["version"]
+license = "MIT"
+authors = [{ name = "Fabian Zills" }]
+dependencies = ["fastapi>=0.137.2", "pydantic>=2.13.4"]
+
+[project.optional-dependencies]
+client = ["httpx>=0.27"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.27",
+    "pyright>=1.1.390",
+    "ruff>=0.8",
+    "pre-commit>=4.0",
+    "uvicorn>=0.49.0",
+]
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.0.0-dev"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/fastapi_rfc9457/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastapi_rfc9457"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]
+filterwarnings = [
+    # Starlette's TestClient now prefers httpx2; the httpx warning is expected.
+    "ignore::DeprecationWarning",
+]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4", "PIE", "RUF"]
+ignore = ["B008"]  # FastAPI's Depends()/Query() defaults are a deliberate pattern
+
+[tool.ruff.lint.per-file-ignores]
+"tests/static/*" = ["F821", "F811", "B018", "E501"]  # intentional type-error fixtures
+
+[tool.pyright]
+include = ["src", "tests/static/valid_usage.py"]
+exclude = ["tests/static/expected_errors.py", "**/_version.py"]
+pythonVersion = "3.11"
+typeCheckingMode = "standard"

fastapi_rfc9457-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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