scim2-models 0.2.12__tar.gz → 0.3.1__tar.gz

{scim2_models-0.2.12 → scim2_models-0.3.1}/.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 ---
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.8.1'
+    rev: 'v0.9.10'
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
@@ -16,11 +16,11 @@ repos:
         exclude: "\\.svg$|\\.map$|\\.min\\.css$|\\.min\\.js$|\\.po$|\\.pot$"
       - id: check-toml
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.13.0
+    rev: v1.15.0
     hooks:
       - id: mypy
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.3.0
+    rev: v2.4.1
     hooks:
     - id: codespell
       additional_dependencies:

{scim2_models-0.2.12 → scim2_models-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: scim2-models
-Version: 0.2.12
+Version: 0.3.1
 Summary: SCIM2 models serialization and validation with pydantic
 Project-URL: documentation, https://scim2-models.readthedocs.io
 Project-URL: repository, https://github.com/python-scim/scim2-models
@@ -208,6 +208,7 @@ License:                                  Apache License
            WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
            See the License for the specific language governing permissions and
            limitations under the License.
+License-File: LICENSE
 Keywords: provisioning,pydantic,rfc7643,rfc7644,scim,scim2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Web Environment

{scim2_models-0.2.12 → scim2_models-0.3.1}/doc/changelog.rst

@@ -1,14 +1,40 @@
 Changelog
 =========
 
+[0.3.1] - 2025-03-07
+--------------------
+
+Fixed
+^^^^^
+- Fix :attr:`~SearchRequest.start_index` and :attr:`~SearchRequest.count` limits. :issue:`84`
+- :attr:`~ListResponse.total_resuls` is required.
+
+[0.3.0] - 2024-12-11
+--------------------
+
+Added
+^^^^^
+- :meth:`Attribute.get_attribute <scim2_models.Attribute.get_attribute>` can be called with brackets.
+
+Changed
+^^^^^^^
+- Add a :paramref:`~scim2_models.BaseModel.model_validate.original`
+  parameter to :meth:`~scim2_models.BaseModel.model_validate`
+  mandatory for :attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`.
+  This *original* value is used to look if :attr:`~scim2_models.Mutability.immutable`
+  parameters have mutated.
+  :issue:`86`
+
 [0.2.12] - 2024-12-09
 ---------------------
+
 Added
 ^^^^^
 - Implement :meth:`Attribute.get_attribute <scim2_models.Attribute.get_attribute>`.
 
 [0.2.11] - 2024-12-08
 ---------------------
+
 Added
 ^^^^^
 - Implement :meth:`Schema.get_attribute <scim2_models.Schema.get_attribute>`.

{scim2_models-0.2.12 → scim2_models-0.3.1}/doc/conf.py

@@ -17,6 +17,7 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinxcontrib.autodoc_pydantic",
     "sphinx_issues",
+    "sphinx_paramlinks",
     "sphinx_togglebutton",
     "myst_parser",
 ]

{scim2_models-0.2.12 → scim2_models-0.3.1}/doc/tutorial.rst

@@ -102,6 +102,13 @@ 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
 ====================================
 

{scim2_models-0.2.12 → scim2_models-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "scim2-models"
-version = "0.2.12"
+version = "0.3.1"
 description = "SCIM2 models serialization and validation with pydantic"
 authors = [{name="Yaal Coop", email="contact@yaal.coop"}]
 license = {file = "LICENSE"}
@@ -48,6 +48,7 @@ doc = [
     "autodoc-pydantic>=2.2.0",
     "myst-parser>=3.0.1",
     "shibuya>=2024.5.15",
+    "sphinx-paramlinks>=0.6.0",
     "sphinx>=7.3.7",
     "sphinx-issues >= 5.0.0",
     "sphinx-togglebutton>=0.3.2",

{scim2_models-0.2.12 → scim2_models-0.3.1}/scim2_models/base.py

@@ -233,9 +233,9 @@ class Context(Enum):
     Should be used for clients building a payload for a resource replacement request,
     and servers validating resource replacement request payloads.
 
-    - When used for serialization, it will not dump attributes annotated with :attr:`~scim2_models.Mutability.read_only` and :attr:`~scim2_models.Mutability.immutable`.
+    - When used for serialization, it will not dump attributes annotated with :attr:`~scim2_models.Mutability.read_only`.
     - When used for validation, it will ignore attributes annotated with :attr:`scim2_models.Mutability.read_only` and raise a :class:`~pydantic.ValidationError`:
-        - when finding attributes annotated with :attr:`~scim2_models.Mutability.immutable`,
+        - when finding attributes annotated with :attr:`~scim2_models.Mutability.immutable` different than :paramref:`~scim2_models.BaseModel.model_validate.original`:
         - when attributes annotated with :attr:`Required.true <scim2_models.Required.true>` are missing on null.
     """
 
@@ -492,12 +492,6 @@ class BaseModel(PydanticBaseModel):
         ):
             raise exc
 
-        if (
-            context == Context.RESOURCE_REPLACEMENT_REQUEST
-            and mutability == Mutability.immutable
-        ):
-            raise exc
-
         if (
             context
             in (Context.RESOURCE_CREATION_REQUEST, Context.RESOURCE_REPLACEMENT_REQUEST)
@@ -604,8 +598,55 @@ class BaseModel(PydanticBaseModel):
 
         return value
 
+    @model_validator(mode="wrap")
+    @classmethod
+    def check_replacement_request_mutability(
+        cls, value: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo
+    ) -> Self:
+        """Check if 'immutable' attributes have been mutated in replacement requests."""
+        from scim2_models.rfc7643.resource import Resource
+
+        value = handler(value)
+
+        context = info.context.get("scim") if info.context else None
+        original = info.context.get("original") if info.context else None
+        if (
+            context == Context.RESOURCE_REPLACEMENT_REQUEST
+            and issubclass(cls, Resource)
+            and original is not None
+        ):
+            cls.check_mutability_issues(original, value)
+        return value
+
+    @classmethod
+    def check_mutability_issues(cls, original: "BaseModel", replacement: "BaseModel"):
+        """Compare two instances, and check for differences of values on the fields marked as immutable."""
+        model = replacement.__class__
+        for field_name in model.model_fields:
+            mutability = model.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},
+                )
+
+            attr_type = model.get_field_root_type(field_name)
+            if is_complex_attribute(attr_type) and not model.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)
+
     def mark_with_schema(self):
-        """Navigate through attributes and sub-attributes of type ComplexAttribute, and mark them with a '_schema' attribute. '_schema' will later be used by 'get_attribute_urn'."""
+        """Navigate through attributes and sub-attributes of type ComplexAttribute, and mark them with a '_schema' attribute.
+
+        '_schema' will later be used by 'get_attribute_urn'.
+        """
         from scim2_models.rfc7643.resource import Resource
 
         for field_name in self.model_fields:
@@ -653,7 +694,8 @@ class BaseModel(PydanticBaseModel):
         scim_ctx = info.context.get("scim") if info.context else None
 
         if (
-            scim_ctx == Context.RESOURCE_CREATION_REQUEST
+            scim_ctx
+            in (Context.RESOURCE_CREATION_REQUEST, Context.RESOURCE_REPLACEMENT_REQUEST)
             and mutability == Mutability.read_only
         ):
             return None
@@ -668,12 +710,6 @@ class BaseModel(PydanticBaseModel):
         ):
             return None
 
-        if scim_ctx == Context.RESOURCE_REPLACEMENT_REQUEST and mutability in (
-            Mutability.immutable,
-            Mutability.read_only,
-        ):
-            return None
-
         return value
 
     def scim_response_serializer(self, value: Any, info: SerializationInfo) -> Any:
@@ -719,10 +755,28 @@ class BaseModel(PydanticBaseModel):
 
     @classmethod
     def model_validate(
-        cls, *args, scim_ctx: Optional[Context] = Context.DEFAULT, **kwargs
+        cls,
+        *args,
+        scim_ctx: Optional[Context] = Context.DEFAULT,
+        original: Optional["BaseModel"] = None,
+        **kwargs,
     ) -> Self:
-        """Validate SCIM payloads and generate model representation by using Pydantic :code:`BaseModel.model_validate`."""
-        kwargs.setdefault("context", {}).setdefault("scim", scim_ctx)
+        """Validate SCIM payloads and generate model representation by using Pydantic :code:`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.
+        """
+        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 _prepare_model_dump(

{scim2_models-0.2.12 → scim2_models-0.3.1}/scim2_models/rfc7643/schema.py

@@ -245,6 +245,12 @@ class Attribute(ComplexAttribute):
                 return sub_attribute
         return None
 
+    def __getitem__(self, name):
+        """Find an attribute by its name."""
+        if attribute := self.get_attribute(name):
+            return attribute
+        raise KeyError(f"This attribute has no '{name}' sub-attribute")
+
 
 class Schema(Resource):
     schemas: Annotated[list[str], Required.true] = [
@@ -280,3 +286,9 @@ class Schema(Resource):
             if attribute.name == attribute_name:
                 return attribute
         return None
+
+    def __getitem__(self, name):
+        """Find an attribute by its name."""
+        if attribute := self.get_attribute(name):
+            return attribute
+        raise KeyError(f"This schema has no '{name}' attribute")

{scim2_models-0.2.12 → scim2_models-0.3.1}/scim2_models/rfc7644/list_response.py

@@ -104,7 +104,13 @@ class ListResponse(Message, Generic[AnyResource], metaclass=ListResponseMetaclas
     def check_results_number(
         cls, value: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo
     ) -> Self:
-        """:rfc:`RFC7644 §3.4.2 <7644#section-3.4.2.4>` indicates that 'resources' must be set if 'totalResults' is non-zero."""
+        """Validate result numbers.
+
+        :rfc:`RFC7644 §3.4.2 <7644#section-3.4.2.4>` indicates that:
+
+        - 'totalResults' is required
+        - 'resources' must be set if 'totalResults' is non-zero.
+        """
         obj = handler(value)
 
         if (
@@ -114,6 +120,12 @@ class ListResponse(Message, Generic[AnyResource], metaclass=ListResponseMetaclas
         ):
             return obj
 
+        if obj.total_results is None:
+            raise PydanticCustomError(
+                "required_error",
+                "Field 'total_results' is required but value is missing or null",
+            )
+
         if obj.total_results > 0 and not obj.resources:
             raise PydanticCustomError(
                 "no_resource_error",

{scim2_models-0.2.12 → scim2_models-0.3.1}/scim2_models/rfc7644/search_request.py

@@ -49,11 +49,11 @@ class SearchRequest(Message):
     @field_validator("start_index")
     @classmethod
     def start_index_floor(cls, value: int) -> int:
-        """According to :rfc:`RFC7644 §3.4.2 <7644#section-3.4.2.4>, start_index values less than 0 are interpreted as 0.
+        """According to :rfc:`RFC7644 §3.4.2 <7644#section-3.4.2.4>, start_index values less than 1 are interpreted as 1.
 
         A value less than 1 SHALL be interpreted as 1.
         """
-        return None if value is None else max(0, value)
+        return None if value is None else max(1, value)
 
     count: Optional[int] = None
     """An integer indicating the desired maximum number of query results per
@@ -62,11 +62,11 @@ class SearchRequest(Message):
     @field_validator("count")
     @classmethod
     def count_floor(cls, value: int) -> int:
-        """According to :rfc:`RFC7644 §3.4.2 <7644#section-3.4.2.4>, count values less than 1 are interpreted as 1.
+        """According to :rfc:`RFC7644 §3.4.2 <7644#section-3.4.2.4>, count values less than 0 are interpreted as 0.
 
-        A value less than 1 SHALL be interpreted as 1.
+        A negative value SHALL be interpreted as 0.
         """
-        return None if value is None else max(1, value)
+        return None if value is None else max(0, value)
 
     @model_validator(mode="after")
     def attributes_validator(self):

{scim2_models-0.2.12 → scim2_models-0.3.1}/tests/test_list_response.py

@@ -217,3 +217,26 @@ def test_list_response_schema_ordering():
         ],
     }
     ListResponse[Union[User[EnterpriseUser], Group]].model_validate(payload)
+
+
+def test_total_results_required():
+    """ListResponse.total_results is required."""
+    payload = {
+        "Resources": [
+            {
+                "schemas": [
+                    "urn:ietf:params:scim:schemas:core:2.0:User",
+                ],
+                "userName": "bjensen@example.com",
+                "id": "foobar",
+            }
+        ],
+    }
+
+    with pytest.raises(
+        ValidationError,
+        match="Field 'total_results' is required but value is missing or null",
+    ):
+        ListResponse[User].model_validate(
+            payload, scim_ctx=Context.RESOURCE_QUERY_RESPONSE
+        )

{scim2_models-0.2.12 → scim2_models-0.3.1}/tests/test_model_serialization.py

@@ -151,6 +151,7 @@ def test_dump_replacement_request(mut_resource):
         "schemas": ["org:example:MutResource"],
         "readWrite": "x",
         "writeOnly": "x",
+        "immutable": "x",
     }
 
 

{scim2_models-0.2.12 → scim2_models-0.3.1}/tests/test_model_validation.py

@@ -4,6 +4,7 @@ from typing import Optional
 import pytest
 from pydantic import ValidationError
 
+from scim2_models.base import ComplexAttribute
 from scim2_models.base import Context
 from scim2_models.base import Mutability
 from scim2_models.base import Required
@@ -144,31 +145,113 @@ def test_validate_replacement_request_mutability():
     """Test query validation for resource model replacement requests.
 
     Attributes marked as:
-    - Mutability.immutable raise a ValidationError
+    - Mutability.immutable raise a ValidationError if different than the 'original' item.
     - Mutability.read_only are ignored
     """
+    with pytest.raises(
+        ValueError,
+        match="Resource queries replacement validation must compare to an original resource",
+    ):
+        MutResource.model_validate(
+            {
+                "readOnly": "x",
+                "readWrite": "x",
+                "writeOnly": "x",
+            },
+            scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+        )
+
+    original = MutResource(read_only="y", read_write="y", write_only="y", immutable="y")
     assert MutResource.model_validate(
         {
             "readOnly": "x",
             "readWrite": "x",
             "writeOnly": "x",
+            "immutable": "y",
         },
         scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+        original=original,
     ) == MutResource(
         schemas=["org:example:MutResource"],
         readWrite="x",
         writeOnly="x",
+        immutable="y",
+    )
+
+    MutResource.model_validate(
+        {
+            "immutable": "y",
+        },
+        scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+        original=original,
     )
 
     with pytest.raises(
         ValidationError,
-        match="Field 'immutable' has mutability 'immutable' but this in not valid in resource replacement request context",
+        match="Field 'immutable' is immutable but the request value is different than the original value.",
     ):
         MutResource.model_validate(
             {
                 "immutable": "x",
             },
             scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+            original=original,
+        )
+
+
+def test_validate_replacement_request_mutability_sub_attributes():
+    """Test query validation for resource model replacement requests.
+
+    Sub-attributes marked as:
+    - Mutability.immutable raise a ValidationError if different than the 'original' item.
+    - Mutability.read_only are ignored
+    """
+
+    class Sub(ComplexAttribute):
+        immutable: Annotated[Optional[str], Mutability.immutable] = None
+
+    class Super(Resource):
+        schemas: Annotated[list[str], Required.true] = ["org:example:Super"]
+        sub: Optional[Sub] = None
+
+    original = Super(sub=Sub(immutable="y"))
+    assert Super.model_validate(
+        {
+            "sub": {
+                "immutable": "y",
+            }
+        },
+        scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+        original=original,
+    ) == Super(
+        schemas=["org:example:Super"],
+        sub=Sub(
+            immutable="y",
+        ),
+    )
+
+    Super.model_validate(
+        {
+            "sub": {
+                "immutable": "y",
+            }
+        },
+        scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+        original=original,
+    )
+
+    with pytest.raises(
+        ValidationError,
+        match="Field 'immutable' is immutable but the request value is different than the original value.",
+    ):
+        Super.model_validate(
+            {
+                "sub": {
+                    "immutable": "x",
+                }
+            },
+            scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+            original=original,
         )
 
 
@@ -378,12 +461,14 @@ def test_validate_creation_and_replacement_request_necessity(context):
     Attributes marked as:
     - Required.true and missing raise a ValidationError
     """
+    original = MutResource(read_only="y", read_write="y", write_only="y", immutable="y")
     assert ReqResource.model_validate(
         {
             "required": "x",
             "optional": "x",
         },
         scim_ctx=context,
+        original=original,
     ) == ReqResource(
         schemas=["org:example:ReqResource"],
         required="x",
@@ -395,6 +480,7 @@ def test_validate_creation_and_replacement_request_necessity(context):
             "required": "x",
         },
         scim_ctx=context,
+        original=original,
     ) == ReqResource(
         schemas=["org:example:ReqResource"],
         required="x",
@@ -408,6 +494,7 @@ def test_validate_creation_and_replacement_request_necessity(context):
             {
                 "optional": "x",
             },
+            original=original,
             scim_ctx=context,
         )
 

{scim2_models-0.2.12 → scim2_models-0.3.1}/tests/test_patch_op.py

@@ -3,7 +3,6 @@ from pydantic import ValidationError
 
 from scim2_models import PatchOp
 from scim2_models import PatchOperation
-from scim2_models.base import Context
 
 
 def test_validate_patchop_case_insensitivith():
@@ -16,7 +15,6 @@ def test_validate_patchop_case_insensitivith():
                 {"op": "ReMove", "path": "userName", "value": "Rivard"},
             ],
         },
-        scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
     ) == PatchOp(
         operations=[
             PatchOperation(
@@ -36,5 +34,4 @@ def test_validate_patchop_case_insensitivith():
             {
                 "operations": [{"op": 42, "path": "userName", "value": "Rivard"}],
             },
-            scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
         )

{scim2_models-0.2.12 → scim2_models-0.3.1}/tests/test_schema.py

@@ -92,13 +92,18 @@ def test_get_schema_attribute(load_sample):
     payload = load_sample("rfc7643-8.7.1-schema-user.json")
     schema = Schema.model_validate(payload)
     assert schema.get_attribute("invalid") is None
+    with pytest.raises(KeyError):
+        schema["invalid"]
 
     assert schema.attributes[0].name == "userName"
     assert schema.attributes[0].mutability == Mutability.read_write
-    schema.get_attribute("userName").mutability = Mutability.read_only
 
+    schema.get_attribute("userName").mutability = Mutability.read_only
     assert schema.attributes[0].mutability == Mutability.read_only
 
+    schema["userName"].mutability = Mutability.read_write
+    assert schema.attributes[0].mutability == Mutability.read_write
+
 
 def test_get_attribute_attribute(load_sample):
     """Test the Schema.get_attribute method."""
@@ -107,9 +112,14 @@ def test_get_attribute_attribute(load_sample):
     attribute = schema.get_attribute("members")
 
     assert attribute.get_attribute("invalid") is None
+    with pytest.raises(KeyError):
+        attribute["invalid"]
 
     assert attribute.sub_attributes[0].name == "value"
     assert attribute.sub_attributes[0].mutability == Mutability.immutable
-    attribute.get_attribute("value").mutability = Mutability.read_only
 
+    attribute.get_attribute("value").mutability = Mutability.read_only
     assert attribute.sub_attributes[0].mutability == Mutability.read_only
+
+    attribute["value"].mutability = Mutability.read_write
+    assert attribute.sub_attributes[0].mutability == Mutability.read_write

{scim2_models-0.2.12 → scim2_models-0.3.1}/tests/test_search_request.py

@@ -29,13 +29,13 @@ def test_start_index_floor():
 
     https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4
 
-        A negative value SHALL be interpreted as 0.
+        A value less than 1 SHALL be interpreted as 1.
     """
     sr = SearchRequest(start_index=100)
     assert sr.start_index == 100
 
-    sr = SearchRequest(start_index=-1)
-    assert sr.start_index == 0
+    sr = SearchRequest(start_index=0)
+    assert sr.start_index == 1
 
 
 def test_count_floor():
@@ -43,16 +43,13 @@ def test_count_floor():
 
     https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4
 
-        A value less than 1 SHALL be interpreted as 1.
+        A negative value SHALL be interpreted as 0.
     """
     sr = SearchRequest(count=100)
     assert sr.count == 100
 
-    sr = SearchRequest(count=0)
-    assert sr.count == 1
-
     sr = SearchRequest(count=-1)
-    assert sr.count == 1
+    assert sr.count == 0
 
 
 def test_attributes_or_excluded_attributes():