feat: Add generate_swagger_response method to ExceptionHandler to support generating responses with documentation_uris. (#41)

Rather than passing the same documentation_uri_template to all calls of
generate_swagger_response, leverage the internal attributes of the
ExceptionHandler.

closes #38

Author: EdgyEdgemond

docs/error.md

@@ -149,10 +149,10 @@ called with the type, title, status and any additional extras provided when the
 error is raised.
 
 ```python
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     documentation_uri_template="https://link-to/my/errors/{type}",
 )
+add_exception_handler(app, eh)
 ```
 
 ```json
@@ -166,10 +166,10 @@ Where a full resolvable documentation uri does not exist, the rfc allows for a
 [tag uri](https://en.wikipedia.org/wiki/Tag_URI_scheme#Format).
 
 ```python
-add_exception_handler(
-    app,
-    documentation_uri_template="tag:my-domain.com,2024-01-01:{type}",
+eh = new_exception_handler(
+    documentation_uri_template="https://link-to/my/errors/{type}",
 )
+add_exception_handler(app, eh)
 ```
 
 ```json
@@ -188,11 +188,11 @@ in cases where the Problem doesn't explicitly define a `type_` attribute, the
 type will default to `about:blank`.
 
 ```python
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     documentation_uri_template="https://link-to/my/errors/{type}",
     strict_rfc9457=True,
 )
+add_exception_handler(app, eh)
 ```
 
 ```json

docs/handlers.md

@@ -24,7 +24,7 @@ A custom handler can then be defined in your application.
 import fastapi
 from rfc9457 import error_class_to_type
 from fastapi_problem.error import Problem
-from fastapi_problem.handler import ExceptionHandler, add_exception_handler
+from fastapi_problem.handler import ExceptionHandler, add_exception_handler, new_exception_handler
 from starlette.requests import Request
 
 from third_party.error import CustomBaseError
@@ -39,12 +39,12 @@ def my_custom_handler(eh: ExceptionHandler, request: Request, exc: CustomBaseErr
     )
 
 app = fastapi.FastAPI()
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     handlers={
         CustomBaseError: my_custom_handler,
     },
 )
+add_exception_handler(app, eh)
 ```
 
 Any instance of CustomBaseError, or any subclasses, that reach the exception
@@ -63,7 +63,7 @@ previously defined, but rather than passing it to handlers, use the
 ```python
 import fastapi
 from fastapi_problem.error import Problem
-from fastapi_problem.handler import ExceptionHandler, add_exception_handler
+from fastapi_problem.handler import ExceptionHandler, add_exception_handler, new_exception_handler
 from starlette.exceptions import HTTPException
 from starlette.requests import Request
 
@@ -73,10 +73,10 @@ def my_custom_handler(eh: ExceptionHandler, request: Request, exc: HTTPException
 
 
 app = fastapi.FastAPI()
-add_exception_handler(
-    app,
+eh = new_excep, new_exception_handler(
     http_exception_handler=my_custom_handler,
 )
+add_exception_handler(app, eh)
 ```
 
 ### Optional handling
@@ -90,7 +90,7 @@ will be pass to the next defined handler.
 import fastapi
 from rfc9457 import error_class_to_type
 from fastapi_problem.error import Problem
-from fastapi_problem.handler import ExceptionHandler, add_exception_handler
+from fastapi_problem.handler import ExceptionHandler, add_exception_handler, new_exception_handler
 from starlette.requests import Request
 
 def no_response_handler(eh: ExceptionHandler, request: Request, exc: RuntimeError) -> Problem | None:
@@ -112,13 +112,13 @@ def base_handler(eh: ExceptionHandler, request: Request, exc: Exception) -> Prob
     )
 
 app = fastapi.FastAPI()
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     handlers={
         RuntimeError: no_response_handler,
         Exception: base_handler,
     },
 )
+add_exception_handler(app, eh)
 ```
 
 At the time of writing there was (is?) a

docs/hooks.md

@@ -12,7 +12,7 @@ for informational purposes such as logging or debugging.
 import logging
 
 import fastapi
-from fastapi_problem.handler import add_exception_handler
+from fastapi_problem.handler import add_exception_handler, new_exception_handler
 from starlette.requests import Request
 
 logger = logging.getLogger(__name__)
@@ -24,10 +24,10 @@ def custom_hook(request: Request, exc: Exception) -> None:
 
 
 app = fastapi.FastAPI()
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     pre_hooks=[custom_hook],
 )
+add_exception_handler(app, eh)
 ```
 
 ## Post Hooks
@@ -40,7 +40,7 @@ xml api etc, the raw content can be reprocessed.).
 
 ```python
 import fastapi
-from fastapi_problem.handler import add_exception_handler
+from fastapi_problem.handler import add_exception_handler, new_exception_handler
 from starlette.requests import Request
 from starlette.responses import Response
 
@@ -55,8 +55,8 @@ def custom_hook(content: dict, request: Request, response: Response) -> Response
 
 
 app = fastapi.FastAPI()
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     post_hooks=[custom_hook],
 )
+add_exception_handler(app, eh)
 ```

docs/usage.md

@@ -6,24 +6,23 @@ import fastapi_problem.handler
 
 
 app = fastapi.FastAPI()
-fastapi_problem.handler.add_exception_handler(app)
+eh = fastapi_problem.handler.new_exception_handler()
+fastapi_problem.handler.add_exception_handler(app, eh)
 ```
 
 A custom logger can be provided using:
 
 ```python
-add_exception_handler(
-    app,
+new_exception_handler(
     logger=...,
 )
 ```
 
 If you require cors headers, you can pass a `fastapi_problem.cors.CorsConfiguration`
-instance to `add_exception_handler(cors=...)`.
+instance to `new_exception_handler(cors=...)`.
 
 ```python
-add_exception_handler(
-    app,
+new_exception_handler(
     cors=CorsConfiguration(
         allow_origins=["*"],
         allow_methods=["*"],
@@ -40,18 +39,18 @@ for all unhandled exceptions.
 
 ```python
 from fastapi_problem.error import StatusProblem
-from fastapi_problem.handler import add_exception_handler
+from fastapi_problem.handler import add_exception_handler, new_exception_handler
 
 class NotFoundError(StatusProblem):
     status = 404
     message = "Endpoint not found."
 
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     unhandled_wrappers={
         "404": NotFoundError,
     },
 )
+add_exception_handler(app, eh)
 ```
 
 If you wish to hide debug messaging from external users, `StripExtrasPostHook`
@@ -64,10 +63,9 @@ allow extras for specific status codes. Allowing expected fields to reach the
 user, while suppressing unexpected server errors etc.
 
 ```python
-from fastapi_problem.handler import StripExtrasPostHook, add_exception_handler
+from fastapi_problem.handler import StripExtrasPostHook, add_exception_handler, new_exception_handler
 
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     post_hooks=[
         StripExtrasPostHook(
             mandatory_fields=["type", "title", "status", "detail", "custom-extra"],
@@ -76,6 +74,7 @@ add_exception_handler(
         )
     ],
 )
+add_exception_handler(app, eh)
 ```
 
 ## Swagger
@@ -88,10 +87,10 @@ opted out of by passing `generic_swagger_defaults=False` when registering the
 exception handlers.
 
 ```python
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     generic_swagger_defaults=False,
 )
+add_exception_handler(app, eh)
 ```
 
 To specify specific error responses per endpoint, when registering the route
@@ -108,9 +107,12 @@ class NotFoundError(StatusProblem):
     title = "Endpoint not found."
 
 
+eh = new_exception_handler()
+add_exception_handler(app, eh)
+
 @app.post(
     "/path",
-    responses={400: generate_swagger_response(NotFoundError)}},
+    responses={400: eh.generate_swagger_response(NotFoundError)}},
 )
 ...
 ```

examples/auth.py

@@ -18,7 +18,7 @@
     ForbiddenProblem,
     UnauthorisedProblem,
 )
-from fastapi_problem.handler import add_exception_handler
+from fastapi_problem.handler import add_exception_handler, new_exception_handler
 
 
 class AuthorizationRequiredError(UnauthorisedProblem):
@@ -46,9 +46,8 @@ async def check_auth(
 
 app = fastapi.FastAPI()
 
-add_exception_handler(
-    app,
-)
+eh = new_exception_handler()
+add_exception_handler(app, eh)
 
 
 @app.get("/authorized")

examples/basic.py

@@ -14,7 +14,7 @@
 import fastapi
 
 from fastapi_problem.error import BadRequestProblem, ServerProblem
-from fastapi_problem.handler import add_exception_handler
+from fastapi_problem.handler import add_exception_handler, new_exception_handler
 
 logging.getLogger("uvicorn.error").disabled = True
 
@@ -29,9 +29,8 @@ class KnownServerProblem(ServerProblem):
 
 app = fastapi.FastAPI()
 
-add_exception_handler(
-    app,
-)
+eh = new_exception_handler()
+add_exception_handler(app, eh)
 
 
 @app.get("/user-error")

examples/builtin.py

@@ -23,15 +23,14 @@
 import fastapi
 import pydantic
 
-from fastapi_problem.handler import add_exception_handler
+from fastapi_problem.handler import add_exception_handler, new_exception_handler
 
 logging.getLogger("uvicorn.error").disabled = True
 
 app = fastapi.FastAPI()
 
-add_exception_handler(
-    app,
-)
+eh = new_exception_handler()
+add_exception_handler(app, eh)
 
 
 @app.get("/validation-error")

examples/custom.py

@@ -19,7 +19,7 @@
 
 import fastapi
 
-from fastapi_problem.handler import add_exception_handler
+from fastapi_problem.handler import add_exception_handler, new_exception_handler
 from fastapi_problem.error import NotFoundProblem, ServerProblem, StatusProblem, UnprocessableProblem
 
 logging.getLogger("uvicorn.error").disabled = True
@@ -44,15 +44,15 @@ class CustomServer(ServerProblem):
 
 app = fastapi.FastAPI()
 
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     unhandled_wrappers={
         "404": CustomNotFound,
         "405": CustomNotAllowed,
         "422": CustomValidation,
         "default": CustomServer,
     },
 )
+add_exception_handler(app, eh)
 
 
 @app.get("/validation-error")

examples/override.py

@@ -14,7 +14,7 @@
 import fastapi
 from starlette.exceptions import HTTPException
 
-from fastapi_problem.handler import ExceptionHandler, add_exception_handler
+from fastapi_problem.handler import ExceptionHandler, add_exception_handler, new_exception_handler
 from fastapi_problem.error import NotFoundProblem, Problem, ServerProblem, StatusProblem
 
 logging.getLogger("uvicorn.error").disabled = True
@@ -48,10 +48,10 @@ def http_exception_handler(
 
 app = fastapi.FastAPI()
 
-add_exception_handler(
-    app,
+eh = new_exception_handler(
     http_exception_handler=http_exception_handler,
 )
+add_exception_handler(app, eh)
 
 
 @app.post("/not-allowed")

pyproject.toml

@@ -116,6 +116,7 @@ select = ["ALL"]
 ignore = [
     "ANN002",  # ParamSpec not available in 3.9
     "ANN003",  # ParamSpec not available in 3.9
+    "E501",    # Handled by ruff format
     "FIX",  # allow TODO
     "D",
 ]