scim2-models 0.3.6__py3-none-any.whl → 0.4.0__py3-none-any.whl

scim2_models/messages/patch_op.py

@@ -0,0 +1,478 @@
+from enum import Enum
+from inspect import isclass
+from typing import Annotated
+from typing import Any
+from typing import Generic
+from typing import Optional
+from typing import TypeVar
+
+from pydantic import Field
+from pydantic import ValidationInfo
+from pydantic import field_validator
+from pydantic import model_validator
+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 ..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 _validate_scim_path_syntax
+from .error import Error
+from .message import Message
+from .message import _get_resource_class
+
+T = TypeVar("T", bound=Resource)
+
+
+class PatchOperation(ComplexAttribute):
+    class Op(str, Enum):
+        replace_ = "replace"
+        remove = "remove"
+        add = "add"
+
+    op: Op
+    """Each PATCH operation object MUST have exactly one "op" member, whose
+    value indicates the operation to perform and MAY be one of "add", "remove",
+    or "replace".
+
+    .. note::
+
+        For the sake of compatibility with Microsoft Entra,
+        despite :rfc:`RFC7644 §3.5.2 <7644#section-3.5.2>`, op is case-insensitive.
+    """
+
+    path: Optional[str] = None
+    """The "path" attribute value is a String containing an attribute path
+    describing the target of the operation."""
+
+    def _validate_mutability(
+        self, resource_class: type[BaseModel], field_name: str
+    ) -> None:
+        """Validate mutability constraints."""
+        # RFC 7644 Section 3.5.2: "Servers should be tolerant of schema extensions"
+        if field_name not in resource_class.model_fields:
+            return
+
+        mutability = resource_class.get_field_annotation(field_name, Mutability)
+
+        # RFC 7643 Section 7: "Attributes with mutability 'readOnly' SHALL NOT be modified"
+        if mutability == Mutability.read_only and self.op in (
+            PatchOperation.Op.add,
+            PatchOperation.Op.replace_,
+        ):
+            raise ValueError(Error.make_mutability_error().detail)
+
+        # 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)
+
+    def _validate_required_attribute(
+        self, resource_class: type[BaseModel], field_name: str
+    ) -> None:
+        """Validate required attribute constraints for remove operations."""
+        # RFC 7644 Section 3.5.2.3: Only validate for remove operations
+        if self.op != PatchOperation.Op.remove:
+            return
+
+        # RFC 7644 Section 3.5.2: "Servers should be tolerant of schema extensions"
+        if field_name not in resource_class.model_fields:
+            return
+
+        required = resource_class.get_field_annotation(field_name, Required)
+
+        # RFC 7643 Section 7: "Required attributes SHALL NOT be removed"
+        if required == Required.true:
+            raise ValueError(Error.make_invalid_value_error().detail)
+
+    @model_validator(mode="after")
+    def validate_operation_requirements(self, info: ValidationInfo) -> Self:
+        """Validate operation requirements according to RFC 7644."""
+        # Only validate in PATCH request context
+        scim_ctx = info.context.get("scim") if info.context else None
+        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"
+        if self.path is None and self.op == PatchOperation.Op.remove:
+            raise ValueError(Error.make_invalid_path_error().detail)
+
+        # 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)
+
+        return self
+
+    value: Optional[Any] = None
+
+    @field_validator("op", mode="before")
+    @classmethod
+    def normalize_op(cls, v: Any) -> Any:
+        """Ignore case for op.
+
+        This brings
+        `compatibility with Microsoft Entra <https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#general>`_:
+
+        Don't require a case-sensitive match on structural elements in SCIM,
+        in particular PATCH op operation values, as defined in section 3.5.2.
+        Microsoft Entra ID emits the values of op as Add, Replace, and Remove.
+        """
+        if isinstance(v, str):
+            return v.lower()
+        return v
+
+
+class PatchOp(Message, Generic[T]):
+    """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.
+    Usage: PatchOp[User], PatchOp[Group], etc.
+
+    .. note::
+        - Always use with a specific type parameter, e.g., PatchOp[User]
+        - PatchOp[Resource] is not allowed - use a concrete subclass instead
+        - Union types are not supported - use a specific resource type
+        - Using PatchOp without a type parameter raises TypeError
+    """
+
+    def __new__(cls, *args, **kwargs):
+        """Create new PatchOp instance with type parameter validation.
+
+        Only handles the case of direct instantiation without type parameter (PatchOp()).
+        All type parameter validation is handled by __class_getitem__.
+        """
+        if (
+            cls.__name__ == "PatchOp"
+            and not hasattr(cls, "__origin__")
+            and not hasattr(cls, "__args__")
+        ):
+            raise TypeError(
+                "PatchOp requires a type parameter. "
+                "Use PatchOp[YourResourceType] instead of PatchOp. "
+                "Example: PatchOp[User], PatchOp[Group], etc."
+            )
+
+        return super().__new__(cls)
+
+    def __class_getitem__(cls, item):
+        """Validate type parameter when creating parameterized type.
+
+        Ensures the type parameter is a concrete Resource subclass (not Resource itself).
+        Rejects invalid types (str, int, etc.) and Union types.
+        """
+        # Check if type parameter is a concrete Resource subclass (not Resource itself)
+        if item is Resource:
+            raise TypeError(
+                "PatchOp requires a concrete Resource subclass, not Resource itself. "
+                "Use PatchOp[User], PatchOp[Group], etc. instead of PatchOp[Resource]."
+            )
+        if not (isclass(item) and issubclass(item, Resource) and item is not Resource):
+            raise TypeError(
+                f"PatchOp type parameter must be a concrete Resource subclass, got {item}. "
+                "Use PatchOp[User], PatchOp[Group], etc."
+            )
+
+        return super().__class_getitem__(item)
+
+    schemas: Annotated[list[str], Required.true] = [
+        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
+    ]
+
+    operations: Annotated[Optional[list[PatchOperation]], 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."""
+
+    @model_validator(mode="after")
+    def validate_operations(self) -> Self:
+        """Validate operations against resource type metadata if available.
+
+        When PatchOp is used with a specific resource type (e.g., PatchOp[User]),
+        this validator will automatically check mutability and required constraints.
+        """
+        resource_class = _get_resource_class(self)
+        if resource_class is None or not self.operations:
+            return self
+
+        # RFC 7644 Section 3.5.2: "Validate each operation against schema constraints"
+        for operation in self.operations:
+            if operation.path is None:
+                continue
+
+            field_name = _extract_field_name(operation.path)
+            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:
+        """Apply all PATCH operations to the given SCIM resource in sequence.
+
+        The resource is modified in-place.
+
+        Each operation in the PatchOp is applied in order, modifying the resource in-place
+        according to :rfc:`RFC7644 §3.5.2 <7644#section-3.5.2>`. Supported operations are
+        "add", "replace", and "remove". If any operation modifies the resource, the method
+        returns True; otherwise, False.
+
+        :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).
+        """
+        if not self.operations:
+            return False
+
+        modified = False
+        # RFC 7644 Section 3.5.2: "Apply each operation in sequence"
+        for operation in self.operations:
+            if self._apply_operation(resource, operation):
+                modified = True
+
+        return modified
+
+    def _apply_operation(self, resource: Resource, operation: PatchOperation) -> bool:
+        """Apply a single patch operation to a resource.
+
+        :return: :data:`True` if the resource was modified, else :data:`False`.
+        """
+        if operation.op in (PatchOperation.Op.add, PatchOperation.Op.replace_):
+            return self._apply_add_replace(resource, operation)
+        if operation.op == PatchOperation.Op.remove:
+            return self._apply_remove(resource, operation)
+
+        raise ValueError(Error.make_invalid_value_error().detail)
+
+    def _apply_add_replace(self, resource: Resource, operation: PatchOperation) -> 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, 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)
+
+    def _apply_root_attributes(self, resource: BaseModel, value: Any) -> bool:
+        """Apply attributes to the resource root."""
+        if not isinstance(value, dict):
+            return False
+
+        modified = False
+        for attr_name, val in value.items():
+            field_name = _find_field_name(type(resource), attr_name)
+            if not field_name:
+                continue
+
+            old_value = getattr(resource, field_name)
+            if old_value != val:
+                setattr(resource, field_name, val)
+                modified = True
+
+        return modified
+
+    def _set_value_at_path(
+        self, resource: Resource, 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 attr_path or not target:
+            raise ValueError(Error.make_invalid_path_error().detail)
+
+        path_parts = attr_path.split(".")
+        if len(path_parts) == 1:
+            return self._set_simple_attribute(target, path_parts[0], value, is_add)
+
+        return self._set_complex_attribute(target, path_parts, value, is_add)
+
+    def _set_simple_attribute(
+        self, 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 self._is_multivalued_field(resource, field_name):
+            return self._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
+
+    def _set_complex_attribute(
+        self, 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 = self._create_parent_object(resource, parent_field_name)
+            if parent_obj is None:
+                return False
+
+        return self._set_value_at_path(parent_obj, sub_path, value, is_add)
+
+    def _is_multivalued_field(self, 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
+        )
+
+    def _handle_multivalued_add(
+        self, resource: BaseModel, field_name: str, value: Any
+    ) -> bool:
+        """Handle adding values to a multi-valued attribute."""
+        current_list = getattr(resource, field_name) or []
+
+        # RFC 7644 Section 3.5.2.1: "Add operation appends values to multi-valued attributes"
+        if isinstance(value, list):
+            return self._add_multiple_values(resource, field_name, current_list, value)
+
+        return self._add_single_value(resource, field_name, current_list, value)
+
+    def _add_multiple_values(
+        self, resource: BaseModel, field_name: str, current_list: list, values: list
+    ) -> 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 self._value_exists_in_list(current_list, new_val):
+                new_values.append(new_val)
+
+        if not new_values:
+            return False
+
+        setattr(resource, field_name, current_list + new_values)
+        return True
+
+    def _add_single_value(
+        self, resource: BaseModel, field_name: str, current_list: list, 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 self._value_exists_in_list(current_list, value):
+            return False
+
+        current_list.append(value)
+        setattr(resource, field_name, current_list)
+        return True
+
+    def _value_exists_in_list(self, current_list: list, new_value: Any) -> bool:
+        """Check if a value already exists in a list."""
+        return any(self._values_match(item, new_value) for item in current_list)
+
+    def _create_parent_object(self, 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
+
+        parent_obj = parent_class()
+        setattr(resource, parent_field_name, parent_obj)
+        return parent_obj
+
+    def _remove_value_at_path(self, resource: Resource, path: str) -> bool:
+        """Remove a value at a specific path."""
+        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)
+
+        parent_attr, *path_parts = attr_path.split(".")
+        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)
+
+        if parent_obj is None:
+            return False
+
+        # 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
+
+        sub_path = ".".join(path_parts)
+        return self._remove_value_at_path(parent_obj, sub_path)
+
+    def _remove_specific_value(
+        self, resource: Resource, path: str, value_to_remove: Any
+    ) -> 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 self._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
+
+    def _values_match(self, value1: Any, value2: Any) -> bool:
+        """Check if two values match, converting BaseModel to dict for comparison."""
+
+        def to_dict(value):
+            return value.model_dump() if isinstance(value, BaseModel) else value
+
+        return to_dict(value1) == to_dict(value2)

scim2_models/{rfc7644 → messages}/search_request.py

@@ -5,7 +5,9 @@ from typing import Optional
 from pydantic import field_validator
 from pydantic import model_validator
 
-from ..base import Required
+from ..annotations import Required
+from ..utils import _validate_scim_path_syntax
+from .error import Error
 from .message import Message
 
 
@@ -24,10 +26,38 @@ class SearchRequest(Message):
     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: Optional[list[str]]) -> Optional[list[str]]:
+        """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: Optional[list[str]] = 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: Optional[list[str]]
+    ) -> Optional[list[str]]:
+        """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: Optional[str] = None
     """The filter string used to request a subset of resources."""
 
@@ -35,6 +65,25 @@ class SearchRequest(Message):
     """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: Optional[str]) -> Optional[str]:
+        """Validate syntax of sort_by attribute path.
+
+        :param v: The sort_by attribute path to validate
+        :type v: Optional[str]
+        :return: The validated sort_by attribute path
+        :rtype: Optional[str]
+        :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"
@@ -48,7 +97,7 @@ class SearchRequest(Message):
 
     @field_validator("start_index")
     @classmethod
-    def start_index_floor(cls, value: int) -> int:
+    def start_index_floor(cls, value: Optional[int]) -> Optional[int]:
         """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.
@@ -61,7 +110,7 @@ class SearchRequest(Message):
 
     @field_validator("count")
     @classmethod
-    def count_floor(cls, value: int) -> int:
+    def count_floor(cls, value: Optional[int]) -> Optional[int]:
         """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.
@@ -69,7 +118,7 @@ class SearchRequest(Message):
         return None if value is None else max(0, value)
 
     @model_validator(mode="after")
-    def attributes_validator(self):
+    def attributes_validator(self) -> "SearchRequest":
         if self.attributes and self.excluded_attributes:
             raise ValueError(
                 "'attributes' and 'excluded_attributes' are mutually exclusive"
@@ -78,12 +127,12 @@ class SearchRequest(Message):
         return self
 
     @property
-    def start_index_0(self):
+    def start_index_0(self) -> Optional[int]:
         """The 0 indexed start index."""
         return self.start_index - 1 if self.start_index is not None else None
 
     @property
-    def stop_index_0(self):
+    def stop_index_0(self) -> Optional[int]:
         """The 0 indexed stop index."""
         return (
             self.start_index_0 + self.count

scim2_models/reference.py

@@ -0,0 +1,82 @@
+from collections import UserString
+from typing import Any
+from typing import Generic
+from typing import TypeVar
+from typing import get_args
+from typing import get_origin
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import core_schema
+from typing_extensions import NewType
+
+from .utils import UNION_TYPES
+
+ReferenceTypes = TypeVar("ReferenceTypes")
+
+URIReference = NewType("URIReference", str)
+ExternalReference = NewType("ExternalReference", str)
+
+
+class Reference(UserString, Generic[ReferenceTypes]):
+    """Reference type as defined in :rfc:`RFC7643 §2.3.7 <7643#section-2.3.7>`.
+
+    References can take different type parameters:
+
+        - Any :class:`~scim2_models.Resource` subtype, or :class:`~typing.ForwardRef` of a Resource subtype, or :data:`~typing.Union` of those,
+        - :data:`~scim2_models.ExternalReference`
+        - :data:`~scim2_models.URIReference`
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        class Foobar(Resource):
+            bff: Reference[User]
+            managers: Reference[Union["User", "Group"]]
+            photo: Reference[ExternalReference]
+            website: Reference[URIReference]
+
+    """
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        _source: type[Any],
+        _handler: GetCoreSchemaHandler,
+    ) -> core_schema.CoreSchema:
+        return core_schema.no_info_after_validator_function(
+            cls._validate,
+            core_schema.union_schema(
+                [core_schema.str_schema(), core_schema.is_instance_schema(cls)]
+            ),
+        )
+
+    @classmethod
+    def _validate(cls, input_value: Any, /) -> str:
+        return str(input_value)
+
+    @classmethod
+    def get_types(cls, type_annotation: Any) -> list[str]:
+        """Get reference types from a type annotation.
+
+        :param type_annotation: Type annotation to extract reference types from
+        :type type_annotation: Any
+        :return: List of reference type strings
+        :rtype: list[str]
+        """
+        first_arg = get_args(type_annotation)[0]
+        types = (
+            get_args(first_arg) if get_origin(first_arg) in UNION_TYPES else [first_arg]
+        )
+
+        def serialize_ref_type(ref_type: Any) -> str:
+            if ref_type == URIReference:
+                return "uri"
+
+            elif ref_type == ExternalReference:
+                return "external"
+
+            return str(get_args(ref_type)[0])
+
+        return list(map(serialize_ref_type, types))

scim2_models/{rfc7643 → resources}/enterprise_user.py

@@ -4,10 +4,10 @@ from typing import Optional
 
 from pydantic import Field
 
-from ..base import ComplexAttribute
-from ..base import Mutability
-from ..base import Reference
-from ..base import Required
+from ..annotations import Mutability
+from ..annotations import Required
+from ..attributes import ComplexAttribute
+from ..reference import Reference
 from .resource import Extension