doc: improve flask integration documentation

Author: azmeuk

doc/guides/_examples/fastapi_example.py

@@ -52,13 +52,14 @@ def resource_location(request, app_record):
 
 
 # -- etag-start --
-def check_etag(record, if_match):
-    """Compare the record's ETag against an ``If-Match`` header value.
+def check_etag(record, request: Request):
+    """Compare the record's ETag against the ``If-Match`` request header.
 
     :param record: The application record.
-    :param if_match: Raw ``If-Match`` header value, or :data:`None`.
+    :param request: The incoming request.
     :raises ~fastapi.HTTPException: If the header is present and does not match.
     """
+    if_match = request.headers.get("If-Match")
     if not if_match:
         return
     if if_match.strip() == "*":
@@ -138,7 +139,7 @@ async def get_user(request: Request, app_record: dict = Depends(resolve_user)):
 @router.patch("/Users/{user_id}")
 async def patch_user(request: Request, app_record: dict = Depends(resolve_user)):
     """Apply a SCIM PatchOp to an existing user."""
-    check_etag(app_record, request.headers.get("If-Match"))
+    check_etag(app_record, request)
     scim_user = to_scim_user(app_record, resource_location(request, app_record))
     patch = PatchOp[User].model_validate(
         await request.json(),
@@ -162,7 +163,7 @@ async def patch_user(request: Request, app_record: dict = Depends(resolve_user))
 @router.put("/Users/{user_id}")
 async def replace_user(request: Request, app_record: dict = Depends(resolve_user)):
     """Replace an existing user with a full SCIM resource."""
-    check_etag(app_record, request.headers.get("If-Match"))
+    check_etag(app_record, request)
     existing_user = to_scim_user(app_record, resource_location(request, app_record))
     replacement = User.model_validate(
         await request.json(),
@@ -190,7 +191,7 @@ async def replace_user(request: Request, app_record: dict = Depends(resolve_user
 @router.delete("/Users/{user_id}")
 async def delete_user(request: Request, app_record: dict = Depends(resolve_user)):
     """Delete an existing user."""
-    check_etag(app_record, request.headers.get("If-Match"))
+    check_etag(app_record, request)
     delete_record(app_record["id"])
     return Response(status_code=HTTPStatus.NO_CONTENT)
 

doc/guides/_examples/flask_example.py

@@ -5,6 +5,7 @@
 from flask import request
 from flask import url_for
 from pydantic import ValidationError
+from werkzeug.exceptions import HTTPException
 from werkzeug.exceptions import PreconditionFailed
 from werkzeug.routing import BaseConverter
 from werkzeug.routing import ValidationError as RoutingValidationError
@@ -51,13 +52,13 @@ def resource_location(app_record):
 
 
 # -- etag-start --
-def check_etag(record, if_match):
-    """Compare the record's ETag against an ``If-Match`` header value.
+def check_etag(record):
+    """Compare the record's ETag against the ``If-Match`` request header.
 
     :param record: The application record.
-    :param if_match: Raw ``If-Match`` header value, or :data:`None`.
     :raises ~werkzeug.exceptions.PreconditionFailed: If the header is present and does not match.
     """
+    if_match = request.headers.get("If-Match")
     if not if_match:
         return
     if if_match.strip() == "*":
@@ -100,11 +101,11 @@ def handle_validation_error(error):
     return scim_error.model_dump_json(), scim_error.status
 
 
-@bp.errorhandler(404)
-def handle_not_found(error):
-    """Turn Flask 404 errors into SCIM error responses."""
-    scim_error = Error(status=404, detail=str(error.description))
-    return scim_error.model_dump_json(), HTTPStatus.NOT_FOUND
+@bp.errorhandler(HTTPException)
+def handle_http_error(error):
+    """Turn HTTP errors into SCIM error responses."""
+    scim_error = Error(status=error.code, detail=str(error.description))
+    return scim_error.model_dump_json(), error.code
 
 
 @bp.errorhandler(SCIMException)
@@ -114,13 +115,6 @@ def handle_scim_error(error):
     return scim_error.model_dump_json(), scim_error.status
 
 
-@bp.errorhandler(PreconditionFailed)
-def handle_precondition_failed(error):
-    """Turn ETag mismatches into SCIM 412 responses."""
-    scim_error = Error(status=412, detail="ETag mismatch")
-    return scim_error.model_dump_json(), HTTPStatus.PRECONDITION_FAILED
-
-
 # -- error-handlers-end --
 # -- refinements-end --
 
@@ -152,7 +146,7 @@ def get_user(app_record):
 @bp.patch("/Users/<user:app_record>")
 def patch_user(app_record):
     """Apply a SCIM PatchOp to an existing user."""
-    check_etag(app_record, request.headers.get("If-Match"))
+    check_etag(app_record)
     scim_user = to_scim_user(app_record, resource_location(app_record))
     patch = PatchOp[User].model_validate(
         request.get_json(),
@@ -177,7 +171,7 @@ def patch_user(app_record):
 @bp.put("/Users/<user:app_record>")
 def replace_user(app_record):
     """Replace an existing user with a full SCIM resource."""
-    check_etag(app_record, request.headers.get("If-Match"))
+    check_etag(app_record)
     existing_user = to_scim_user(app_record, resource_location(app_record))
     replacement = User.model_validate(
         request.get_json(),
@@ -204,7 +198,7 @@ def replace_user(app_record):
 @bp.delete("/Users/<user:app_record>")
 def delete_user(app_record):
     """Delete an existing user."""
-    check_etag(app_record, request.headers.get("If-Match"))
+    check_etag(app_record)
     delete_record(app_record["id"])
     return "", HTTPStatus.NO_CONTENT
 

doc/guides/fastapi.rst

@@ -170,8 +170,8 @@ Resource versioning (ETags)
 
 SCIM supports resource versioning through HTTP ETags
 (:rfc:`RFC 7644 §3.14 <7644#section-3.14>`).
-``check_etag`` compares the record's ETag against the ``If-Match`` header and
-raises an :class:`~fastapi.HTTPException` on mismatch.
+``check_etag`` reads the ``If-Match`` header from the incoming request, compares it against
+the record's ETag and raises an :class:`~fastapi.HTTPException` on mismatch.
 ``make_etag`` computes a weak ETag from each record and populates
 :attr:`~scim2_models.Meta.version`.
 

doc/guides/flask.rst

@@ -55,7 +55,7 @@ record and lets Flask handle the not-found case before entering the view.
 Error handlers
 ^^^^^^^^^^^^^^
 
-The error handlers keep Pydantic validation errors and Flask 404s aligned with SCIM
+The error handlers keep Pydantic validation errors and HTTP errors aligned with SCIM
 responses.
 
 .. literalinclude:: _examples/flask_example.py
@@ -68,9 +68,8 @@ If :meth:`~scim2_models.Resource.model_validate`, Flask routes the
 SCIM :class:`~scim2_models.Error` response.
 ``handle_scim_error`` catches any :class:`~scim2_models.SCIMException` (uniqueness, mutability, …)
 and returns the appropriate SCIM :class:`~scim2_models.Error` response.
-``handle_precondition_failed`` catches
-:class:`~werkzeug.exceptions.PreconditionFailed` errors raised by
-``check_etag`` and returns a 412.
+``handle_http_error`` catches any :class:`~werkzeug.exceptions.HTTPException`
+(404, 412, 405, …) and returns the corresponding SCIM :class:`~scim2_models.Error` response.
 
 Endpoints
 =========
@@ -164,8 +163,8 @@ Resource versioning (ETags)
 
 SCIM supports resource versioning through HTTP ETags
 (:rfc:`RFC 7644 §3.14 <7644#section-3.14>`).
-``check_etag`` compares the record's ETag against the ``If-Match`` header and
-raises :class:`~werkzeug.exceptions.PreconditionFailed` on mismatch.
+``check_etag`` reads the ``If-Match`` header from the current request, compares it against
+the record's ETag and raises :class:`~werkzeug.exceptions.PreconditionFailed` on mismatch.
 ``make_etag`` computes a weak ETag from each record and populates
 :attr:`~scim2_models.Meta.version`.