feat: add Resource.replace() for PUT immutability verification

Extract public replace() method on Resource to verify that immutable
fields have not been modified, per RFC 7644 §3.5.1. Deprecate the
'original' parameter of model_validate().

Author: azmeuk

doc/changelog.rst

@@ -4,6 +4,14 @@ Changelog
 [0.6.8] - Unreleased
 --------------------
 
+Added
+^^^^^
+- :class:`~scim2_models.MutabilityException` handler in framework integration examples (FastAPI, Flask, Django).
+
+Deprecated
+^^^^^^^^^^
+- The ``original`` parameter of :meth:`~scim2_models.base.BaseModel.model_validate` is deprecated. Use :meth:`~scim2_models.Resource.replace` on the validated instance instead. Will be removed in 0.8.0.
+
 Fixed
 ^^^^^
 - PATCH operations on :attr:`~scim2_models.Mutability.immutable` fields are now validated at runtime per :rfc:`RFC 7644 §3.5.2 <7644#section-3.5.2>`: ``add`` is only allowed when the field has no previous value, ``replace`` is only allowed with the same value, and ``remove`` is only allowed on unset fields.

doc/guides/_examples/django_example.py

@@ -13,6 +13,7 @@
 from scim2_models import Context
 from scim2_models import Error
 from scim2_models import ListResponse
+from scim2_models import MutabilityException
 from scim2_models import PatchOp
 from scim2_models import ResourceType
 from scim2_models import ResponseParameters
@@ -152,10 +153,13 @@ def put(self, request, app_record):
             replacement = User.model_validate(
                 json.loads(request.body),
                 scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
-                original=existing_user,
             )
+            replacement.replace(existing_user)
         except ValidationError as error:
             return scim_validation_error(error)
+        except MutabilityException as error:
+            scim_error = error.to_error()
+            return scim_response(scim_error.model_dump_json(), scim_error.status)
 
         replacement.id = existing_user.id
         updated_record = from_scim_user(replacement)

doc/guides/_examples/fastapi_example.py

@@ -11,6 +11,7 @@
 from scim2_models import Context
 from scim2_models import Error
 from scim2_models import ListResponse
+from scim2_models import MutabilityException
 from scim2_models import PatchOp
 from scim2_models import ResourceType
 from scim2_models import ResponseParameters
@@ -93,6 +94,13 @@ async def handle_precondition_failed(request, error):
     return Response(
         scim_error.model_dump_json(), status_code=HTTPStatus.PRECONDITION_FAILED
     )
+
+
+@app.exception_handler(MutabilityException)
+async def handle_mutability_error(request, error):
+    """Turn mutability violations into SCIM error responses."""
+    scim_error = error.to_error()
+    return Response(scim_error.model_dump_json(), status_code=scim_error.status)
 # -- error-handlers-end --
 # -- refinements-end --
 
@@ -151,8 +159,8 @@ async def replace_user(request: Request, app_record: dict = Depends(resolve_user
     replacement = User.model_validate(
         await request.json(),
         scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
-        original=existing_user,
     )
+    replacement.replace(existing_user)
 
     replacement.id = existing_user.id
     updated_record = from_scim_user(replacement)

doc/guides/_examples/flask_example.py

@@ -11,6 +11,7 @@
 from scim2_models import Context
 from scim2_models import Error
 from scim2_models import ListResponse
+from scim2_models import MutabilityException
 from scim2_models import PatchOp
 from scim2_models import ResourceType
 from scim2_models import ResponseParameters
@@ -99,6 +100,13 @@ 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
+
+
+@bp.errorhandler(MutabilityException)
+def handle_mutability_error(error):
+    """Turn mutability violations into SCIM error responses."""
+    scim_error = error.to_error()
+    return scim_error.model_dump_json(), scim_error.status
 # -- error-handlers-end --
 # -- refinements-end --
 
@@ -156,8 +164,8 @@ def replace_user(app_record):
     replacement = User.model_validate(
         request.get_json(),
         scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
-        original=existing_user,
     )
+    replacement.replace(existing_user)
 
     replacement.id = existing_user.id
     updated_record = from_scim_user(replacement)

doc/guides/django.rst

@@ -121,8 +121,9 @@ For ``GET``, parse query parameters with :class:`~scim2_models.ResponseParameter
 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.
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, then call
+:meth:`~scim2_models.Resource.replace` to verify that immutable attributes
+have not been modified.
 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`,

doc/guides/fastapi.rst

@@ -129,10 +129,9 @@ 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`.
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, then call
+:meth:`~scim2_models.Resource.replace` to verify that immutable attributes
+have not been modified.
 
 .. literalinclude:: _examples/fastapi_example.py
    :language: python

doc/guides/flask.rst

@@ -122,10 +122,9 @@ 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`.
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, then call
+:meth:`~scim2_models.Resource.replace` to verify that immutable attributes
+have not been modified.
 
 .. literalinclude:: _examples/flask_example.py
    :language: python

doc/tutorial.rst

@@ -124,13 +124,6 @@ fields with unexpected values will raise :class:`~pydantic.ValidationError`:
     ... except pydantic.ValidationError:
     ...    obj = Error(...)
 
-.. note::
-
-   With the :attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST` context,
-   :meth:`~scim2_models.BaseModel.model_validate` takes an additional
-   :paramref:`~scim2_models.BaseModel.model_validate.original` argument that is used to compare
-   :attr:`~scim2_models.Mutability.immutable` attributes, and raise an exception when they have mutated.
-
 Attributes inclusions and exclusions
 ====================================
 
@@ -479,6 +472,29 @@ Client applications can use this to dynamically discover server resources by bro
           :language: json
           :caption: schema-group.json
 
+Replace operations
+==================
+
+When handling a ``PUT`` request, validate the incoming payload with the
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST` context, then call
+:meth:`~scim2_models.Resource.replace` against the existing resource to
+verify that :attr:`~scim2_models.Mutability.immutable` attributes have not been
+modified.
+
+.. doctest::
+
+    >>> from scim2_models import User, Context
+    >>> from scim2_models.exceptions import MutabilityException
+    >>> existing = User(user_name="bjensen")
+    >>> replacement = User.model_validate(
+    ...     {"userName": "bjensen"},
+    ...     scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+    ... )
+    >>> replacement.replace(existing)
+
+If an immutable attribute differs, a :class:`~scim2_models.MutabilityException`
+is raised.
+
 Patch operations
 ================
 

scim2_models/base.py

@@ -1,3 +1,4 @@
+import warnings
 from inspect import isclass
 from typing import Any
 from typing import Optional
@@ -23,6 +24,7 @@
 from scim2_models.annotations import Required
 from scim2_models.annotations import Returned
 from scim2_models.context import Context
+from scim2_models.exceptions import MutabilityException
 from scim2_models.utils import UNION_TYPES
 from scim2_models.utils import _find_field_name
 from scim2_models.utils import _normalize_attribute_name
@@ -410,7 +412,10 @@ def check_replacement_request_mutability(
             and issubclass(cls, Resource)
             and original is not None
         ):
-            cls._check_mutability_issues(original, obj)
+            try:
+                obj._check_immutable_fields(original)
+            except MutabilityException as exc:
+                raise exc.as_pydantic_error() from exc
         return obj
 
     @model_validator(mode="after")
@@ -456,35 +461,30 @@ def check_primary_attribute_uniqueness(self, info: ValidationInfo) -> Self:
 
         return self
 
-    @classmethod
-    def _check_mutability_issues(
-        cls, original: "BaseModel", replacement: "BaseModel"
-    ) -> None:
-        """Compare two instances, and check for differences of values on the fields marked as immutable."""
+    def _check_immutable_fields(self, original: Self) -> None:
+        """Check that immutable fields have not been modified compared to *original*.
+
+        Recursively checks nested single-valued complex attributes.
+        """
         from .attributes import is_complex_attribute
 
-        model = replacement.__class__
-        for field_name in model.model_fields:
-            mutability = model.get_field_annotation(field_name, Mutability)
+        for field_name in type(self).model_fields:
+            mutability = type(self).get_field_annotation(field_name, Mutability)
             if mutability == Mutability.immutable and getattr(
                 original, field_name
-            ) != getattr(replacement, field_name):
-                raise PydanticCustomError(
-                    "mutability_error",
-                    "Field '{field_name}' is immutable but the request value is different than the original value.",
-                    {"field_name": field_name},
-                )
+            ) != getattr(self, field_name):
+                raise MutabilityException(attribute=field_name, mutability="immutable")
 
-            attr_type = model.get_field_root_type(field_name)
+            attr_type = type(self).get_field_root_type(field_name)
             if (
                 attr_type
                 and is_complex_attribute(attr_type)
-                and not model.get_field_multiplicity(field_name)
+                and not type(self).get_field_multiplicity(field_name)
             ):
                 original_val = getattr(original, field_name)
-                replacement_value = getattr(replacement, field_name)
-                if original_val is not None and replacement_value is not None:
-                    cls._check_mutability_issues(original_val, replacement_value)
+                replacement_val = getattr(self, field_name)
+                if original_val is not None and replacement_val is not None:
+                    replacement_val._check_immutable_fields(original_val)
 
     def _set_complex_attribute_urns(self) -> None:
         """Navigate through attributes and sub-attributes of type ComplexAttribute, and mark them with a '_attribute_urn' attribute.
@@ -611,22 +611,30 @@ def model_validate(
         original: Optional["BaseModel"] = None,
         **kwargs: Any,
     ) -> Self:
-        """Validate SCIM payloads and generate model representation by using Pydantic :code:`BaseModel.model_validate`.
+        """Validate SCIM payloads and generate model representation by using Pydantic :meth:`~pydantic.BaseModel.model_validate`.
 
         :param scim_ctx: The SCIM :class:`~scim2_models.Context` in which the validation happens.
         :param original: If this parameter is set during :attr:`~Context.RESOURCE_REPLACEMENT_REQUEST`,
             :attr:`~scim2_models.Mutability.immutable` parameters will be compared against the *original* model value.
             An exception is raised if values are different.
+
+            .. deprecated:: 0.6.7
+                Use :meth:`replace` on the validated instance instead.
+                Will be removed in 0.8.0.
         """
+        if original is not None:
+            warnings.warn(
+                "The 'original' parameter is deprecated, "
+                "use the 'replace' method on the validated instance instead. "
+                "Will be removed in 0.8.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         context = kwargs.setdefault("context", {})
         context.setdefault("scim", scim_ctx)
         context.setdefault("original", original)
 
-        if scim_ctx == Context.RESOURCE_REPLACEMENT_REQUEST and original is None:
-            raise ValueError(
-                "Resource queries replacement validation must compare to an original resource"
-            )
-
         return super().model_validate(*args, **kwargs)
 
     def get_attribute_urn(self, field_name: str) -> str:

scim2_models/resources/resource.py

@@ -153,6 +153,20 @@ class Resource(ScimObject, Generic[AnyExtension]):
     meta: Annotated[Meta | None, Mutability.read_only, Returned.default] = None
     """A complex attribute containing resource metadata."""
 
+    def replace(self, original: Self) -> None:
+        """Verify that no immutable field has been modified compared to *original*.
+
+        Intended to be called after parsing a PUT request body, to enforce
+        :rfc:`RFC 7644 §3.5.1 <7644#section-3.5.1>`: if one or more values
+        are already set for an immutable attribute, the input values MUST match.
+
+        Recursively checks nested single-valued complex attributes.
+
+        :param original: The original resource state to compare against.
+        :raises MutabilityException: If an immutable field value differs.
+        """
+        self._check_immutable_fields(original)
+
     @classmethod
     def __class_getitem__(cls, item: Any) -> type["Resource[Any]"]:
         """Create a Resource class with extension fields dynamically added."""