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

scim2_models/__init__.py

@@ -7,6 +7,18 @@ from .attributes import ComplexAttribute
 from .attributes import MultiValuedComplexAttribute
 from .base import BaseModel
 from .context import Context
+from .exceptions import InvalidFilterException
+from .exceptions import InvalidPathException
+from .exceptions import InvalidSyntaxException
+from .exceptions import InvalidValueException
+from .exceptions import InvalidVersionException
+from .exceptions import MutabilityException
+from .exceptions import NoTargetException
+from .exceptions import PathNotFoundException
+from .exceptions import SCIMException
+from .exceptions import SensitiveException
+from .exceptions import TooManyException
+from .exceptions import UniquenessException
 from .messages.bulk import BulkOperation
 from .messages.bulk import BulkRequest
 from .messages.bulk import BulkResponse
@@ -16,6 +28,10 @@ from .messages.message import Message
 from .messages.patch_op import PatchOp
 from .messages.patch_op import PatchOperation
 from .messages.search_request import SearchRequest
+from .path import URN
+from .path import Path
+from .reference import URI
+from .reference import External
 from .reference import ExternalReference
 from .reference import Reference
 from .reference import URIReference
@@ -72,6 +88,7 @@ __all__ = [
     "EnterpriseUser",
     "Entitlement",
     "Error",
+    "External",
     "ExternalReference",
     "Extension",
     "Filter",
@@ -79,13 +96,22 @@ __all__ = [
     "GroupMember",
     "GroupMembership",
     "Im",
+    "InvalidFilterException",
+    "InvalidPathException",
+    "InvalidSyntaxException",
+    "InvalidValueException",
+    "InvalidVersionException",
     "ListResponse",
     "Manager",
     "Message",
     "Meta",
     "Mutability",
+    "MutabilityException",
     "MultiValuedComplexAttribute",
     "Name",
+    "NoTargetException",
+    "Path",
+    "PathNotFoundException",
     "Patch",
     "PatchOp",
     "PatchOperation",
@@ -97,13 +123,19 @@ __all__ = [
     "ResourceType",
     "Returned",
     "Role",
+    "SCIMException",
     "Schema",
     "SchemaExtension",
     "SearchRequest",
+    "SensitiveException",
     "ServiceProviderConfig",
     "Sort",
+    "TooManyException",
     "Uniqueness",
+    "UniquenessException",
+    "URI",
     "URIReference",
+    "URN",
     "User",
     "X509Certificate",
 ]

scim2_models/attributes.py

@@ -34,7 +34,11 @@ class MultiValuedComplexAttribute(ComplexAttribute):
 
     primary: bool | None = None
     """A Boolean value indicating the 'primary' or preferred attribute value
-    for this attribute."""
+    for this attribute.
+
+    Per :rfc:`RFC 7643 §2.4 <7643#section-2.4>`, the primary attribute value
+    ``True`` MUST appear no more than once in a multi-valued attribute list.
+    """
 
     display: Annotated[str | None, Mutability.immutable] = None
     """A human-readable name, primarily used for display purposes."""

scim2_models/base.py

@@ -29,12 +29,21 @@ from scim2_models.utils import _normalize_attribute_name
 from scim2_models.utils import _to_camel
 
 
-def _contains_attribute_or_subattributes(
-    attribute_urns: list[str], attribute_urn: str
-) -> bool:
-    return attribute_urn in attribute_urns or any(
-        item.startswith(f"{attribute_urn}.") or item.startswith(f"{attribute_urn}:")
-        for item in attribute_urns
+def _is_attribute_requested(requested_urns: list[str], current_urn: str) -> bool:
+    """Check if an attribute should be included based on the requested URNs.
+
+    Returns True if:
+    - The current attribute is explicitly requested
+    - A sub-attribute of the current attribute is requested
+    - The current attribute is a sub-attribute of a requested attribute
+    """
+    return (
+        current_urn in requested_urns
+        or any(
+            item.startswith(f"{current_urn}.") or item.startswith(f"{current_urn}:")
+            for item in requested_urns
+        )
+        or any(current_urn.startswith(f"{item}.") for item in requested_urns)
     )
 
 
@@ -355,6 +364,49 @@ class BaseModel(PydanticBaseModel):
             cls._check_mutability_issues(original, obj)
         return obj
 
+    @model_validator(mode="after")
+    def check_primary_attribute_uniqueness(self, info: ValidationInfo) -> Self:
+        """Validate that only one attribute can be marked as primary in multi-valued lists.
+
+        Per RFC 7643 Section 2.4: The primary attribute value 'true' MUST appear no more than once.
+        """
+        scim_context = info.context.get("scim") if info.context else None
+        if not scim_context or scim_context == Context.DEFAULT:
+            return self
+
+        for field_name in self.__class__.model_fields:
+            if not self.get_field_multiplicity(field_name):
+                continue
+
+            field_value = getattr(self, field_name)
+            if field_value is None:
+                continue
+
+            element_type = self.get_field_root_type(field_name)
+            if (
+                element_type is None
+                or not isclass(element_type)
+                or not issubclass(element_type, PydanticBaseModel)
+                or "primary" not in element_type.model_fields
+            ):
+                continue
+
+            primary_count = sum(
+                1 for item in field_value if getattr(item, "primary", None) is True
+            )
+
+            if primary_count > 1:
+                raise PydanticCustomError(
+                    "primary_uniqueness_error",
+                    "Field '{field_name}' has {count} items marked as primary, but only one is allowed per RFC 7643",
+                    {
+                        "field_name": field_name,
+                        "count": primary_count,
+                    },
+                )
+
+        return self
+
     @classmethod
     def _check_mutability_issues(
         cls, original: "BaseModel", replacement: "BaseModel"
@@ -397,7 +449,9 @@ class BaseModel(PydanticBaseModel):
             main_schema = self._attribute_urn
             separator = "."
         else:
-            main_schema = self.__class__.model_fields["schemas"].default[0]
+            main_schema = getattr(self.__class__, "__schema__", None)
+            if main_schema is None:
+                return
             separator = ":"
 
         for field_name in self.__class__.model_fields:
@@ -478,9 +532,7 @@ class BaseModel(PydanticBaseModel):
         if returnability == Returned.default and (
             (
                 included_urns
-                and not _contains_attribute_or_subattributes(
-                    included_urns, attribute_urn
-                )
+                and not _is_attribute_requested(included_urns, attribute_urn)
             )
             or attribute_urn in excluded_urns
         ):
@@ -533,13 +585,12 @@ class BaseModel(PydanticBaseModel):
         """
         from scim2_models.resources.resource import Extension
 
-        main_schema = self.__class__.model_fields["schemas"].default[0]
+        main_schema = getattr(self.__class__, "__schema__", None)
         field = self.__class__.model_fields[field_name]
         alias = field.serialization_alias or field_name
         field_type = self.get_field_root_type(field_name)
-        full_urn = (
-            alias
-            if isclass(field_type) and issubclass(field_type, Extension)
-            else f"{main_schema}:{alias}"
-        )
-        return full_urn
+        if isclass(field_type) and issubclass(field_type, Extension):
+            return alias
+        if main_schema is None:
+            return alias
+        return f"{main_schema}:{alias}"

scim2_models/exceptions.py

@@ -0,0 +1,265 @@
+"""SCIM exceptions corresponding to RFC 7644 error types.
+
+This module provides a hierarchy of exceptions that map to SCIM protocol errors.
+Each exception can be converted to a :class:`~scim2_models.Error` response object
+or to a :class:`~pydantic_core.PydanticCustomError` for use in Pydantic validators.
+"""
+
+from typing import TYPE_CHECKING
+from typing import Any
+
+from pydantic_core import PydanticCustomError
+
+if TYPE_CHECKING:
+    from .messages.error import Error
+
+
+class SCIMException(Exception):
+    """Base exception for SCIM protocol errors.
+
+    Each subclass corresponds to a scimType defined in :rfc:`RFC 7644 Table 9 <7644#section-3.12>`.
+    """
+
+    status: int = 400
+    scim_type: str = ""
+    _default_detail: str = "A SCIM error occurred"
+
+    def __init__(self, *, detail: str | None = None, **context: Any):
+        self.context = context
+        self._detail = detail
+        super().__init__(detail or self._default_detail)
+
+    @property
+    def detail(self) -> str:
+        """The error detail message."""
+        return self._detail or self._default_detail
+
+    def to_error(self) -> "Error":
+        """Convert this exception to a SCIM Error response object."""
+        from .messages.error import Error
+
+        return Error(
+            status=self.status,
+            scim_type=self.scim_type or None,
+            detail=str(self),
+        )
+
+    def as_pydantic_error(self) -> PydanticCustomError:
+        """Convert to PydanticCustomError for use in Pydantic validators."""
+        return PydanticCustomError(
+            f"scim_{self.scim_type}" if self.scim_type else "scim_error",
+            str(self),
+            {"scim_type": self.scim_type, "status": self.status, **self.context},
+        )
+
+
+class InvalidFilterException(SCIMException):
+    """The specified filter syntax was invalid.
+
+    Corresponds to scimType ``invalidFilter`` with HTTP status 400.
+
+    :rfc:`RFC 7644 Section 3.4.2.2 <7644#section-3.4.2.2>`
+    """
+
+    status = 400
+    scim_type = "invalidFilter"
+    _default_detail = (
+        "The specified filter syntax was invalid, "
+        "or the specified attribute and filter comparison combination is not supported"
+    )
+
+    def __init__(self, *, filter: str | None = None, **kw: Any):
+        self.filter = filter
+        super().__init__(**kw)
+
+
+class TooManyException(SCIMException):
+    """The specified filter yields too many results.
+
+    Corresponds to scimType ``tooMany`` with HTTP status 400.
+
+    :rfc:`RFC 7644 Section 3.4.2.2 <7644#section-3.4.2.2>`
+    """
+
+    status = 400
+    scim_type = "tooMany"
+    _default_detail = (
+        "The specified filter yields many more results "
+        "than the server is willing to calculate or process"
+    )
+
+
+class UniquenessException(SCIMException):
+    """One or more attribute values are already in use or reserved.
+
+    Corresponds to scimType ``uniqueness`` with HTTP status 409.
+
+    :rfc:`RFC 7644 Section 3.3.1 <7644#section-3.3.1>`
+    """
+
+    status = 409
+    scim_type = "uniqueness"
+    _default_detail = (
+        "One or more of the attribute values are already in use or are reserved"
+    )
+
+    def __init__(
+        self, *, attribute: str | None = None, value: Any | None = None, **kw: Any
+    ):
+        self.attribute = attribute
+        self.value = value
+        super().__init__(**kw)
+
+
+class MutabilityException(SCIMException):
+    """The attempted modification is not compatible with the attribute's mutability.
+
+    Corresponds to scimType ``mutability`` with HTTP status 400.
+
+    :rfc:`RFC 7644 Section 3.5.2 <7644#section-3.5.2>`
+    """
+
+    status = 400
+    scim_type = "mutability"
+    _default_detail = (
+        "The attempted modification is not compatible with the target attribute's "
+        "mutability or current state"
+    )
+
+    def __init__(
+        self,
+        *,
+        attribute: str | None = None,
+        mutability: str | None = None,
+        operation: str | None = None,
+        **kw: Any,
+    ):
+        self.attribute = attribute
+        self.mutability = mutability
+        self.operation = operation
+        super().__init__(**kw)
+
+
+class InvalidSyntaxException(SCIMException):
+    """The request body message structure was invalid.
+
+    Corresponds to scimType ``invalidSyntax`` with HTTP status 400.
+
+    :rfc:`RFC 7644 Section 3.12 <7644#section-3.12>`
+    """
+
+    status = 400
+    scim_type = "invalidSyntax"
+    _default_detail = (
+        "The request body message structure was invalid "
+        "or did not conform to the request schema"
+    )
+
+
+class InvalidPathException(SCIMException):
+    """The path attribute was invalid or malformed.
+
+    Corresponds to scimType ``invalidPath`` with HTTP status 400.
+
+    :rfc:`RFC 7644 Section 3.5.2 <7644#section-3.5.2>`
+    """
+
+    status = 400
+    scim_type = "invalidPath"
+    _default_detail = "The path attribute was invalid or malformed"
+
+    def __init__(self, *, path: str | None = None, **kw: Any):
+        self.path = path
+        super().__init__(**kw)
+
+
+class PathNotFoundException(InvalidPathException):
+    """The path references a non-existent field.
+
+    This is a specialized form of :class:`InvalidPathException`.
+    """
+
+    _default_detail = "The specified path references a non-existent field"
+
+    def __init__(self, *, path: str | None = None, field: str | None = None, **kw: Any):
+        self.field = field
+        super().__init__(path=path, **kw)
+
+    def __str__(self) -> str:
+        if self._detail:
+            return self._detail
+        if self.field:
+            return f"Field not found: {self.field}"
+        return self._default_detail
+
+
+class NoTargetException(SCIMException):
+    """The specified path did not yield a target that could be operated on.
+
+    Corresponds to scimType ``noTarget`` with HTTP status 400.
+
+    :rfc:`RFC 7644 Section 3.5.2 <7644#section-3.5.2>`
+    """
+
+    status = 400
+    scim_type = "noTarget"
+    _default_detail = (
+        "The specified path did not yield an attribute or attribute value "
+        "that could be operated on"
+    )
+
+    def __init__(self, *, path: str | None = None, **kw: Any):
+        self.path = path
+        super().__init__(**kw)
+
+
+class InvalidValueException(SCIMException):
+    """A required value was missing or the value was not compatible.
+
+    Corresponds to scimType ``invalidValue`` with HTTP status 400.
+
+    :rfc:`RFC 7644 Section 3.12 <7644#section-3.12>`
+    """
+
+    status = 400
+    scim_type = "invalidValue"
+    _default_detail = (
+        "A required value was missing, or the value specified was not compatible "
+        "with the operation or attribute type, or resource schema"
+    )
+
+    def __init__(
+        self, *, attribute: str | None = None, reason: str | None = None, **kw: Any
+    ):
+        self.attribute = attribute
+        self.reason = reason
+        super().__init__(**kw)
+
+
+class InvalidVersionException(SCIMException):
+    """The specified SCIM protocol version is not supported.
+
+    Corresponds to scimType ``invalidVers`` with HTTP status 400.
+
+    :rfc:`RFC 7644 Section 3.13 <7644#section-3.13>`
+    """
+
+    status = 400
+    scim_type = "invalidVers"
+    _default_detail = "The specified SCIM protocol version is not supported"
+
+
+class SensitiveException(SCIMException):
+    """The request cannot be completed due to sensitive information in the URI.
+
+    Corresponds to scimType ``sensitive`` with HTTP status 400.
+
+    :rfc:`RFC 7644 Section 7.5.2 <7644#section-7.5.2>`
+    """
+
+    status = 400
+    scim_type = "sensitive"
+    _default_detail = (
+        "The specified request cannot be completed, due to the passing of sensitive "
+        "information in a request URI"
+    )

scim2_models/messages/bulk.py

@@ -5,8 +5,8 @@ from typing import Any
 from pydantic import Field
 from pydantic import PlainSerializer
 
-from ..annotations import Required
 from ..attributes import ComplexAttribute
+from ..path import URN
 from ..utils import _int_to_str
 from .message import Message
 
@@ -53,9 +53,7 @@ class BulkRequest(Message):
         The models for Bulk operations are defined, but their behavior is not implemented nor tested yet.
     """
 
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:BulkRequest")
 
     fail_on_errors: int | None = None
     """An integer specifying the number of errors that the service provider
@@ -76,9 +74,7 @@ class BulkResponse(Message):
         The models for Bulk operations are defined, but their behavior is not implemented nor tested yet.
     """
 
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:api:messages:2.0:BulkResponse"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:BulkResponse")
 
     operations: list[BulkOperation] | None = Field(
         None, serialization_alias="Operations"