doc: document PUT in web integrations

Author: azmeuk

doc/guides/_examples/django_example.py

@@ -84,7 +84,7 @@ def handler404(request, exception):
 # -- single-resource-start --
 @method_decorator(csrf_exempt, name="dispatch")
 class UserView(View):
-    """Handle GET, PATCH and DELETE on one SCIM user resource."""
+    """Handle GET, PUT, PATCH and DELETE on one SCIM user resource."""
 
     def get(self, request, app_record):
         try:
@@ -105,6 +105,31 @@ def delete(self, request, app_record):
         delete_record(app_record["id"])
         return scim_response("", HTTPStatus.NO_CONTENT)
 
+    def put(self, request, app_record):
+        existing_user = to_scim_user(app_record)
+        try:
+            replacement = User.model_validate(
+                json.loads(request.body),
+                scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+                original=existing_user,
+            )
+        except ValidationError as error:
+            return scim_validation_error(error)
+
+        replacement.id = existing_user.id
+        updated_record = from_scim_user(replacement)
+        try:
+            save_record(updated_record)
+        except ValueError as error:
+            return scim_uniqueness_error(error)
+
+        response_user = to_scim_user(updated_record)
+        return scim_response(
+            response_user.model_dump_json(
+                scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE
+            )
+        )
+
     def patch(self, request, app_record):
         try:
             patch = PatchOp[User].model_validate(

doc/guides/_examples/flask_example.py

@@ -119,6 +119,31 @@ def patch_user(app_record):
 # -- patch-user-end --
 
 
+# -- put-user-start --
+@bp.put("/Users/<user:app_record>")
+def replace_user(app_record):
+    """Replace an existing user with a full SCIM resource."""
+    existing_user = to_scim_user(app_record)
+    replacement = User.model_validate(
+        request.get_json(),
+        scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+        original=existing_user,
+    )
+
+    replacement.id = existing_user.id
+    updated_record = from_scim_user(replacement)
+    save_record(updated_record)
+
+    response_user = to_scim_user(updated_record)
+    return (
+        response_user.model_dump_json(
+            scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE
+        ),
+        HTTPStatus.OK,
+    )
+# -- put-user-end --
+
+
 # -- delete-user-start --
 @bp.delete("/Users/<user:app_record>")
 def delete_user(app_record):

doc/guides/django.rst

@@ -1,5 +1,5 @@
-Django Integration
-------------------
+Django
+------
 
 This guide shows a minimal SCIM integration with `Django <https://www.djangoproject.com/>`_
 and :mod:`scim2_models`.
@@ -103,11 +103,16 @@ any other collection.
 Single resource
 ^^^^^^^^^^^^^^^
 
-``UserView`` handles ``GET``, ``PATCH`` and ``DELETE`` on ``/Users/<id>``.
+``UserView`` handles ``GET``, ``PUT``, ``PATCH`` and ``DELETE`` on ``/Users/<id>``.
 For ``GET``, parse query parameters with :class:`~scim2_models.ResponseParameters` to honour the
 ``attributes`` and ``excludedAttributes`` query parameters, convert the native record to a
 SCIM resource, and serialize with :attr:`~scim2_models.Context.RESOURCE_QUERY_RESPONSE`.
 For ``DELETE``, remove the record and return an empty 204 response.
+For ``PUT``, validate the full replacement payload with
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, passing the ``original`` resource
+so that immutable attributes are checked for unintended modifications.
+Convert back to native and persist, then serialize with
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_RESPONSE`.
 For ``PATCH``, validate the payload with :attr:`~scim2_models.Context.RESOURCE_PATCH_REQUEST`,
 apply it with :meth:`~scim2_models.PatchOp.patch` (generic, works with any resource type),
 convert back to native and persist, then serialize with

doc/guides/flask.rst

@@ -1,5 +1,5 @@
-Flask Integration
------------------
+Flask
+-----
 
 This guide shows a minimal SCIM server built with `Flask <https://flask.palletsprojects.com/>`_
 and :mod:`scim2_models`.
@@ -115,6 +115,20 @@ convert back to native and persist, then serialize the result with
    :start-after: # -- patch-user-start --
    :end-before: # -- patch-user-end --
 
+PUT /Users/<id>
+^^^^^^^^^^^^^^^
+
+Validate the full replacement payload with
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, passing the ``original`` resource
+so that immutable attributes are checked for unintended modifications.
+Convert back to native and persist, then serialize the result with
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_RESPONSE`.
+
+.. literalinclude:: _examples/flask_example.py
+   :language: python
+   :start-after: # -- put-user-start --
+   :end-before: # -- put-user-end --
+
 
 GET /Users
 ^^^^^^^^^^

doc/tutorial.rst

@@ -16,7 +16,7 @@ The standard Python dot notation uses snake_case attribute names, while the brac
     >>> user["nickName"] = "Babs"
     >>> user["name.familyName"] = "Jensen"
 
-Attributes can be removed with ``del``.
+Attributes can be removed with ``del`` or by assigning :data:`None` to the attribute.
 
 .. doctest::
 

tests/test_doc_examples.py

@@ -78,6 +78,17 @@ def test_flask_example_smoke():
     assert duplicate_response.status_code == 409
     assert duplicate_response.get_json()["scimType"] == "uniqueness"
 
+    put_response = client.put(
+        f"/scim/v2/Users/{user_id}",
+        json={
+            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
+            "userName": "bjensen@example.com",
+            "displayName": "Barbara J.",
+        },
+    )
+    assert put_response.status_code == 200
+    assert put_response.get_json()["displayName"] == "Barbara J."
+
 
 def test_django_example_smoke():
     from django.conf import settings
@@ -166,3 +177,17 @@ def test_django_example_smoke():
         )
         assert duplicate_response.status_code == 409
         assert json.loads(duplicate_response.content)["scimType"] == "uniqueness"
+
+        put_response = client.put(
+            f"/scim/v2/Users/{user_id}",
+            data=json.dumps(
+                {
+                    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
+                    "userName": "bjensen@example.com",
+                    "displayName": "Barbara J.",
+                }
+            ),
+            content_type="application/scim+json",
+        )
+        assert put_response.status_code == 200
+        assert json.loads(put_response.content)["displayName"] == "Barbara J."