scim2-models 0.5.2__py3-none-any.whl → 0.6.0__py3-none-any.whl

scim2_models/messages/patch_op.py

@@ -5,6 +5,7 @@ from typing import Any
 from typing import Generic
 from typing import TypeVar
 
+from pydantic import BaseModel as PydanticBaseModel
 from pydantic import Field
 from pydantic import ValidationInfo
 from pydantic import field_validator
@@ -14,22 +15,20 @@ from typing_extensions import Self
 from ..annotations import Mutability
 from ..annotations import Required
 from ..attributes import ComplexAttribute
-from ..base import BaseModel
 from ..context import Context
+from ..exceptions import InvalidValueException
+from ..exceptions import MutabilityException
+from ..exceptions import NoTargetException
+from ..path import URN
+from ..path import Path
 from ..resources.resource import Resource
-from ..urn import _resolve_path_to_target
-from ..utils import _extract_field_name
-from ..utils import _find_field_name
-from ..utils import _get_path_parts
-from ..utils import _validate_scim_path_syntax
-from .error import Error
 from .message import Message
 from .message import _get_resource_class
 
-T = TypeVar("T", bound=Resource[Any])
+ResourceT = TypeVar("ResourceT", bound=Resource[Any])
 
 
-class PatchOperation(ComplexAttribute):
+class PatchOperation(ComplexAttribute, Generic[ResourceT]):
     class Op(str, Enum):
         replace_ = "replace"
         remove = "remove"
@@ -46,7 +45,7 @@ class PatchOperation(ComplexAttribute):
         despite :rfc:`RFC7644 §3.5.2 <7644#section-3.5.2>`, op is case-insensitive.
     """
 
-    path: str | None = None
+    path: Path[ResourceT] | None = None
     """The "path" attribute value is a String containing an attribute path
     describing the target of the operation."""
 
@@ -65,11 +64,15 @@ class PatchOperation(ComplexAttribute):
             PatchOperation.Op.add,
             PatchOperation.Op.replace_,
         ):
-            raise ValueError(Error.make_mutability_error().detail)
+            raise MutabilityException(
+                attribute=field_name, mutability="readOnly", operation=self.op.value
+            ).as_pydantic_error()
 
         # RFC 7643 Section 7: "Attributes with mutability 'immutable' SHALL NOT be updated"
         if mutability == Mutability.immutable and self.op == PatchOperation.Op.replace_:
-            raise ValueError(Error.make_mutability_error().detail)
+            raise MutabilityException(
+                attribute=field_name, mutability="immutable", operation=self.op.value
+            ).as_pydantic_error()
 
     def _validate_required_attribute(
         self, resource_class: type[Resource[Any]], field_name: str
@@ -87,7 +90,9 @@ class PatchOperation(ComplexAttribute):
 
         # RFC 7643 Section 7: "Required attributes SHALL NOT be removed"
         if required == Required.true:
-            raise ValueError(Error.make_invalid_value_error().detail)
+            raise InvalidValueException(
+                detail="required attribute cannot be removed", attribute=field_name
+            ).as_pydantic_error()
 
     @model_validator(mode="after")
     def validate_operation_requirements(self, info: ValidationInfo) -> Self:
@@ -97,17 +102,18 @@ class PatchOperation(ComplexAttribute):
         if scim_ctx != Context.RESOURCE_PATCH_REQUEST:
             return self
 
-        # RFC 7644 Section 3.5.2: "Path syntax validation according to ABNF grammar"
-        if self.path is not None and not _validate_scim_path_syntax(self.path):
-            raise ValueError(Error.make_invalid_path_error().detail)
-
-        # RFC 7644 Section 3.5.2.3: "Path is required for remove operations"
+        # RFC 7644 Section 3.5.2.2: "If 'path' is unspecified, the operation
+        # fails with HTTP status code 400 and a 'scimType' error of 'noTarget'"
         if self.path is None and self.op == PatchOperation.Op.remove:
-            raise ValueError(Error.make_invalid_path_error().detail)
+            raise NoTargetException(
+                detail="Remove operation requires a path"
+            ).as_pydantic_error()
 
         # RFC 7644 Section 3.5.2.1: "Value is required for add operations"
         if self.op == PatchOperation.Op.add and self.value is None:
-            raise ValueError(Error.make_invalid_value_error().detail)
+            raise InvalidValueException(
+                detail="value is required for add operations"
+            ).as_pydantic_error()
 
         return self
 
@@ -130,10 +136,10 @@ class PatchOperation(ComplexAttribute):
         return v
 
 
-class PatchOp(Message, Generic[T]):
+class PatchOp(Message, Generic[ResourceT]):
     """Patch Operation as defined in :rfc:`RFC7644 §3.5.2 <7644#section-3.5.2>`.
 
-    Type parameter T is required and must be a concrete Resource subclass.
+    Type parameter ResourceT is required and must be a concrete Resource subclass.
     Usage: PatchOp[User], PatchOp[Group], etc.
 
     .. note::
@@ -205,12 +211,10 @@ class PatchOp(Message, Generic[T]):
 
         return super().__class_getitem__(typevar_values)
 
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:PatchOp")
 
-    operations: Annotated[list[PatchOperation] | None, Required.true] = Field(
-        None, serialization_alias="Operations", min_length=1
+    operations: Annotated[list[PatchOperation[ResourceT]] | None, Required.true] = (
+        Field(None, serialization_alias="Operations", min_length=1)
     )
     """The body of an HTTP PATCH request MUST contain the attribute
     "Operations", whose value is an array of one or more PATCH operations."""
@@ -225,7 +229,9 @@ class PatchOp(Message, Generic[T]):
         # RFC 7644: The body of an HTTP PATCH request MUST contain the attribute "Operations"
         scim_ctx = info.context.get("scim") if info.context else None
         if scim_ctx == Context.RESOURCE_PATCH_REQUEST and self.operations is None:
-            raise ValueError(Error.make_invalid_value_error().detail)
+            raise InvalidValueException(
+                detail="operations attribute is required"
+            ).as_pydantic_error()
 
         resource_class = _get_resource_class(self)
         if resource_class is None or not self.operations:
@@ -236,13 +242,13 @@ class PatchOp(Message, Generic[T]):
             if operation.path is None:
                 continue
 
-            field_name = _extract_field_name(operation.path)
+            field_name = operation.path.parts[0] if operation.path.parts else None
             operation._validate_mutability(resource_class, field_name)  # type: ignore[arg-type]
             operation._validate_required_attribute(resource_class, field_name)  # type: ignore[arg-type]
 
         return self
 
-    def patch(self, resource: T) -> bool:
+    def patch(self, resource: ResourceT) -> bool:
         """Apply all PATCH operations to the given SCIM resource in sequence.
 
         The resource is modified in-place.
@@ -252,10 +258,14 @@ class PatchOp(Message, Generic[T]):
         "add", "replace", and "remove". If any operation modifies the resource, the method
         returns True; otherwise, False.
 
+        Per :rfc:`RFC 7644 §3.5.2 <7644#section-3.5.2>`, when an operation sets a value's
+        ``primary`` sub-attribute to ``True``, any other values in the same multi-valued
+        attribute will have their ``primary`` set to ``False`` automatically.
+
         :param resource: The SCIM resource to patch. This object is modified in-place.
-        :type resource: T
         :return: True if the resource was modified by any operation, False otherwise.
-        :raises ValueError: If an operation is invalid (e.g., invalid path, forbidden mutation).
+        :raises InvalidValueException: If multiple values are marked as primary in a single
+            operation, or if multiple primary values already exist before the patch.
         """
         if not self.operations:
             return False
@@ -269,7 +279,7 @@ class PatchOp(Message, Generic[T]):
         return modified
 
     def _apply_operation(
-        self, resource: Resource[Any], operation: PatchOperation
+        self, resource: Resource[Any], operation: PatchOperation[ResourceT]
     ) -> bool:
         """Apply a single patch operation to a resource.
 
@@ -280,257 +290,113 @@ class PatchOp(Message, Generic[T]):
         if operation.op == PatchOperation.Op.remove:
             return self._apply_remove(resource, operation)
 
-        raise ValueError(Error.make_invalid_value_error().detail)
+        raise InvalidValueException(detail=f"unsupported operation: {operation.op}")
 
     def _apply_add_replace(
-        self, resource: Resource[Any], operation: PatchOperation
+        self, resource: Resource[Any], operation: PatchOperation[ResourceT]
     ) -> bool:
         """Apply an add or replace operation."""
-        # RFC 7644 Section 3.5.2.1: "If path is specified, add/replace at that path"
-        if operation.path is not None:
-            return self._set_value_at_path(
-                resource,
-                operation.path,
-                operation.value,
-                is_add=operation.op == PatchOperation.Op.add,
-            )
-
-        # RFC 7644 Section 3.5.2.1: "If no path specified, add/replace at root level"
-        return self._apply_root_attributes(resource, operation.value)
-
-    def _apply_remove(self, resource: Resource[Any], operation: PatchOperation) -> bool:
-        """Apply a remove operation."""
-        # RFC 7644 Section 3.5.2.3: "Path is required for remove operations"
-        if operation.path is None:
-            raise ValueError(Error.make_invalid_path_error().detail)
-
-        # RFC 7644 Section 3.5.2.3: "If a value is specified, remove only that value"
-        if operation.value is not None:
-            return self._remove_specific_value(
-                resource, operation.path, operation.value
-            )
-
-        return self._remove_value_at_path(resource, operation.path)
-
-    @classmethod
-    def _apply_root_attributes(cls, resource: BaseModel, value: Any) -> bool:
-        """Apply attributes to the resource root."""
-        if not isinstance(value, dict):
-            return False
+        before_state = self._capture_primary_state(resource)
 
-        modified = False
-        for attr_name, val in value.items():
-            field_name = _find_field_name(type(resource), attr_name)
-            if not field_name:
-                continue
+        path = operation.path if operation.path is not None else Path("")
+        modified = path.set(
+            resource,  # type: ignore[arg-type]
+            operation.value,
+            is_add=operation.op == PatchOperation.Op.add,
+        )
 
-            old_value = getattr(resource, field_name)
-            if old_value != val:
-                setattr(resource, field_name, val)
-                modified = True
+        if modified:
+            self._normalize_primary_after_patch(resource, before_state)
 
         return modified
 
-    @classmethod
-    def _set_value_at_path(
-        cls, resource: Resource[Any], path: str, value: Any, is_add: bool
-    ) -> bool:
-        """Set a value at a specific path."""
-        target, attr_path = _resolve_path_to_target(resource, path)
-
-        if not target:
-            raise ValueError(Error.make_invalid_path_error().detail)
-
-        if not attr_path:
-            if not isinstance(value, dict):
-                raise ValueError(Error.make_invalid_path_error().detail)
-
-            updated_data = {**target.model_dump(), **value}
-            updated_target = type(target).model_validate(updated_data)
-            target.__dict__.update(updated_target.__dict__)
-            return True
-
-        path_parts = _get_path_parts(attr_path)
-        if len(path_parts) == 1:
-            return cls._set_simple_attribute(target, path_parts[0], value, is_add)
-
-        return cls._set_complex_attribute(target, path_parts, value, is_add)
-
-    @classmethod
-    def _set_simple_attribute(
-        cls, resource: BaseModel, attr_name: str, value: Any, is_add: bool
-    ) -> bool:
-        """Set a value on a simple (non-nested) attribute."""
-        field_name = _find_field_name(type(resource), attr_name)
-        if not field_name:
-            raise ValueError(Error.make_no_target_error().detail)
-
-        # RFC 7644 Section 3.5.2.1: "For multi-valued attributes, add operation appends values"
-        if is_add and cls._is_multivalued_field(resource, field_name):
-            return cls._handle_multivalued_add(resource, field_name, value)
-
-        old_value = getattr(resource, field_name)
-        if old_value == value:
-            return False
-
-        setattr(resource, field_name, value)
-        return True
-
-    @classmethod
-    def _set_complex_attribute(
-        cls, resource: BaseModel, path_parts: list[str], value: Any, is_add: bool
-    ) -> bool:
-        """Set a value on a complex (nested) attribute."""
-        parent_attr = path_parts[0]
-        sub_path = ".".join(path_parts[1:])
-
-        parent_field_name = _find_field_name(type(resource), parent_attr)
-        if not parent_field_name:
-            raise ValueError(Error.make_no_target_error().detail)
-
-        parent_obj = getattr(resource, parent_field_name)
-        if parent_obj is None:
-            parent_obj = cls._create_parent_object(resource, parent_field_name)
-            if parent_obj is None:
-                return False
-
-        return cls._set_value_at_path(parent_obj, sub_path, value, is_add)
-
-    @classmethod
-    def _is_multivalued_field(cls, resource: BaseModel, field_name: str) -> bool:
-        """Check if a field is multi-valued."""
-        return hasattr(resource, field_name) and type(resource).get_field_multiplicity(
-            field_name
-        )
-
-    @classmethod
-    def _handle_multivalued_add(
-        cls, resource: BaseModel, field_name: str, value: Any
-    ) -> bool:
-        """Handle adding values to a multi-valued attribute."""
-        current_list = getattr(resource, field_name) or []
+    def _capture_primary_state(self, resource: Resource[Any]) -> dict[str, set[int]]:
+        """Capture indices of elements with primary=True for each multi-valued attribute."""
+        state: dict[str, set[int]] = {}
+        for field_name in type(resource).model_fields:
+            if not resource.get_field_multiplicity(field_name):
+                continue
 
-        # RFC 7644 Section 3.5.2.1: "Add operation appends values to multi-valued attributes"
-        if isinstance(value, list):
-            return cls._add_multiple_values(resource, field_name, current_list, value)
+            field_value = getattr(resource, field_name, None)
+            if not field_value:
+                continue
 
-        return cls._add_single_value(resource, field_name, current_list, value)
+            element_type = resource.get_field_root_type(field_name)
+            if (
+                not element_type
+                or not isclass(element_type)
+                or not issubclass(element_type, PydanticBaseModel)
+                or "primary" not in element_type.model_fields
+            ):
+                continue
 
-    @classmethod
-    def _add_multiple_values(
-        cls,
-        resource: BaseModel,
-        field_name: str,
-        current_list: list[Any],
-        values: list[Any],
-    ) -> bool:
-        """Add multiple values to a multi-valued attribute."""
-        new_values = []
-        # RFC 7644 Section 3.5.2.1: "Do not add duplicate values"
-        for new_val in values:
-            if not cls._value_exists_in_list(current_list, new_val):
-                new_values.append(new_val)
-
-        if not new_values:
-            return False
+            primary_indices = {
+                i
+                for i, item in enumerate(field_value)
+                if getattr(item, "primary", None) is True
+            }
+            state[field_name] = primary_indices
 
-        setattr(resource, field_name, current_list + new_values)
-        return True
+        return state
 
-    @classmethod
-    def _add_single_value(
-        cls, resource: BaseModel, field_name: str, current_list: list[Any], value: Any
-    ) -> bool:
-        """Add a single value to a multi-valued attribute."""
-        # RFC 7644 Section 3.5.2.1: "Do not add duplicate values"
-        if cls._value_exists_in_list(current_list, value):
-            return False
-
-        current_list.append(value)
-        setattr(resource, field_name, current_list)
-        return True
+    def _normalize_primary_after_patch(
+        self, resource: Resource[Any], before_state: dict[str, set[int]]
+    ) -> None:
+        """Normalize primary attributes after a patch operation.
 
-    @classmethod
-    def _value_exists_in_list(cls, current_list: list[Any], new_value: Any) -> bool:
-        """Check if a value already exists in a list."""
-        return any(cls._values_match(item, new_value) for item in current_list)
+        Per :rfc:`RFC 7644 §3.5.2 <7644#section-3.5.2>`: a PATCH operation that
+        sets a value's "primary" sub-attribute to "true" SHALL cause the server
+        to automatically set "primary" to "false" for any other values.
+        """
+        for field_name in type(resource).model_fields:
+            if not resource.get_field_multiplicity(field_name):
+                continue
 
-    @classmethod
-    def _create_parent_object(cls, resource: BaseModel, parent_field_name: str) -> Any:
-        """Create a parent object if it doesn't exist."""
-        parent_class = type(resource).get_field_root_type(parent_field_name)
-        if not parent_class or not isclass(parent_class):
-            return None
+            field_value = getattr(resource, field_name, None)
+            if not field_value:
+                continue
 
-        parent_obj = parent_class()
-        setattr(resource, parent_field_name, parent_obj)
-        return parent_obj
+            element_type = resource.get_field_root_type(field_name)
+            if (
+                not element_type
+                or not isclass(element_type)
+                or not issubclass(element_type, PydanticBaseModel)
+                or "primary" not in element_type.model_fields
+            ):
+                continue
 
-    @classmethod
-    def _remove_value_at_path(cls, resource: Resource[Any], path: str) -> bool:
-        """Remove a value at a specific path."""
-        target, attr_path = _resolve_path_to_target(resource, path)
+            current_primary_indices = {
+                i
+                for i, item in enumerate(field_value)
+                if getattr(item, "primary", None) is True
+            }
 
-        # RFC 7644 Section 3.5.2.3: "Path must resolve to a valid attribute"
-        if not attr_path or not target:
-            raise ValueError(Error.make_invalid_path_error().detail)
+            if len(current_primary_indices) <= 1:
+                continue
 
-        parent_attr, *path_parts = _get_path_parts(attr_path)
-        field_name = _find_field_name(type(target), parent_attr)
-        if not field_name:
-            raise ValueError(Error.make_no_target_error().detail)
-        parent_obj = getattr(target, field_name)
+            before_primaries = before_state.get(field_name, set())
+            new_primaries = current_primary_indices - before_primaries
 
-        if parent_obj is None:
-            return False
+            if len(new_primaries) > 1:
+                raise InvalidValueException(
+                    detail=f"Multiple values marked as primary in field '{field_name}'"
+                )
 
-        # RFC 7644 Section 3.5.2.3: "Remove entire attribute if no sub-path"
-        if not path_parts:
-            setattr(target, field_name, None)
-            return True
+            if not new_primaries:
+                raise InvalidValueException(
+                    detail=f"Multiple primary values already exist in field '{field_name}'"
+                )
 
-        sub_path = ".".join(path_parts)
-        return cls._remove_value_at_path(parent_obj, sub_path)
+            keep_index = next(iter(new_primaries))
+            for i in current_primary_indices:
+                if i != keep_index:
+                    field_value[i].primary = False
 
-    @classmethod
-    def _remove_specific_value(
-        cls, resource: Resource[Any], path: str, value_to_remove: Any
+    def _apply_remove(
+        self, resource: Resource[Any], operation: PatchOperation[ResourceT]
     ) -> bool:
-        """Remove a specific value from a multi-valued attribute."""
-        target, attr_path = _resolve_path_to_target(resource, path)
-
-        # RFC 7644 Section 3.5.2.3: "Path must resolve to a valid attribute"
-        if not attr_path or not target:
-            raise ValueError(Error.make_invalid_path_error().detail)
-
-        field_name = _find_field_name(type(target), attr_path)
-        if not field_name:
-            raise ValueError(Error.make_no_target_error().detail)
-
-        current_list = getattr(target, field_name)
-        if not isinstance(current_list, list):
-            return False
-
-        new_list = []
-        modified = False
-        # RFC 7644 Section 3.5.2.3: "Remove matching values from multi-valued attributes"
-        for item in current_list:
-            if not cls._values_match(item, value_to_remove):
-                new_list.append(item)
-            else:
-                modified = True
-
-        if modified:
-            setattr(target, field_name, new_list if new_list else None)
-            return True
-
-        return False
-
-    @classmethod
-    def _values_match(cls, value1: Any, value2: Any) -> bool:
-        """Check if two values match, converting BaseModel to dict for comparison."""
-
-        def to_dict(value: Any) -> dict[str, Any]:
-            return value.model_dump() if isinstance(value, BaseModel) else value
+        """Apply a remove operation."""
+        if operation.path is None:
+            raise NoTargetException(detail="Remove operation requires a path")
 
-        return to_dict(value1) == to_dict(value2)
+        return operation.path.delete(resource, operation.value)  # type: ignore[arg-type]

scim2_models/messages/search_request.py

@@ -1,12 +1,11 @@
 from enum import Enum
-from typing import Annotated
+from typing import Any
 
 from pydantic import field_validator
 from pydantic import model_validator
 
-from ..annotations import Required
-from ..utils import _validate_scim_path_syntax
-from .error import Error
+from ..path import URN
+from ..path import Path
 from .message import Message
 
 
@@ -16,71 +15,24 @@ class SearchRequest(Message):
     https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.3
     """
 
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:SearchRequest")
 
-    attributes: list[str] | None = None
+    attributes: list[Path[Any]] | None = None
     """A multi-valued list of strings indicating the names of resource
     attributes to return in the response, overriding the set of attributes that
     would be returned by default."""
 
-    @field_validator("attributes")
-    @classmethod
-    def validate_attributes_syntax(cls, v: list[str] | None) -> list[str] | None:
-        """Validate syntax of attribute paths."""
-        if v is None:
-            return v
-
-        for attr in v:
-            if not _validate_scim_path_syntax(attr):
-                raise ValueError(Error.make_invalid_path_error().detail)
-
-        return v
-
-    excluded_attributes: list[str] | None = None
+    excluded_attributes: list[Path[Any]] | None = None
     """A multi-valued list of strings indicating the names of resource
     attributes to be removed from the default set of attributes to return."""
 
-    @field_validator("excluded_attributes")
-    @classmethod
-    def validate_excluded_attributes_syntax(
-        cls, v: list[str] | None
-    ) -> list[str] | None:
-        """Validate syntax of excluded attribute paths."""
-        if v is None:
-            return v
-
-        for attr in v:
-            if not _validate_scim_path_syntax(attr):
-                raise ValueError(Error.make_invalid_path_error().detail)
-
-        return v
-
     filter: str | None = None
     """The filter string used to request a subset of resources."""
 
-    sort_by: str | None = None
+    sort_by: Path[Any] | None = None
     """A string indicating the attribute whose value SHALL be used to order the
     returned responses."""
 
-    @field_validator("sort_by")
-    @classmethod
-    def validate_sort_by_syntax(cls, v: str | None) -> str | None:
-        """Validate syntax of sort_by attribute path.
-
-        :param v: The sort_by attribute path to validate
-        :return: The validated sort_by attribute path
-        :raises ValueError: If sort_by attribute path has invalid syntax
-        """
-        if v is None:
-            return v
-
-        if not _validate_scim_path_syntax(v):
-            raise ValueError(Error.make_invalid_path_error().detail)
-
-        return v
-
     class SortOrder(str, Enum):
         ascending = "ascending"
         descending = "descending"
@@ -95,7 +47,7 @@ class SearchRequest(Message):
     @field_validator("start_index")
     @classmethod
     def start_index_floor(cls, value: int | None) -> int | None:
-        """According to :rfc:`RFC7644 §3.4.2 <7644#section-3.4.2.4>, start_index values less than 1 are interpreted as 1.
+        """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.
         """
@@ -108,7 +60,7 @@ class SearchRequest(Message):
     @field_validator("count")
     @classmethod
     def count_floor(cls, value: int | None) -> int | None:
-        """According to :rfc:`RFC7644 §3.4.2 <7644#section-3.4.2.4>, count values less than 0 are interpreted as 0.
+        """According to :rfc:`RFC7644 §3.4.2 <7644#section-3.4.2.4>`, count values less than 0 are interpreted as 0.
 
         A negative value SHALL be interpreted as 0.
         """