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

scim2_models/constants.py

@@ -1,4 +1,4 @@
-PYTHON_RESERVED_WORDS = [
+PYTHON_RESERVED_WORDS: list[str] = [
     "False",
     "def",
     "if",
@@ -34,5 +34,5 @@ PYTHON_RESERVED_WORDS = [
     "pass",
 ]
 
-PYDANTIC_RESERVED_WORDS = ["schema"]
-RESERVED_WORDS = PYTHON_RESERVED_WORDS + PYDANTIC_RESERVED_WORDS
+PYDANTIC_RESERVED_WORDS: list[str] = ["schema"]
+RESERVED_WORDS: list[str] = PYTHON_RESERVED_WORDS + PYDANTIC_RESERVED_WORDS

scim2_models/context.py

@@ -0,0 +1,168 @@
+from enum import Enum
+from enum import auto
+
+
+class Context(Enum):
+    """Represent the different HTTP contexts detailed in :rfc:`RFC7644 §3.2 <7644#section-3.2>`.
+
+    Contexts are intended to be used during model validation and serialization.
+    For instance a client preparing a resource creation POST request can use
+    :code:`resource.model_dump(Context.RESOURCE_CREATION_REQUEST)` and
+    the server can then validate it with
+    :code:`resource.model_validate(Context.RESOURCE_CREATION_REQUEST)`.
+    """
+
+    DEFAULT = auto()
+    """The default context.
+
+    All fields are accepted during validation, and all fields are
+    serialized during a dump.
+    """
+
+    RESOURCE_CREATION_REQUEST = auto()
+    """The resource creation request context.
+
+    Should be used for clients building a payload for a resource creation request,
+    and servers validating resource creation request payloads.
+
+    - When used for serialization, it will not dump attributes annotated with :attr:`~scim2_models.Mutability.read_only`.
+    - When used for validation, it will raise a :class:`~pydantic.ValidationError`:
+        - when finding attributes annotated with :attr:`~scim2_models.Mutability.read_only`,
+        - when attributes annotated with :attr:`Required.true <scim2_models.Required.true>` are missing on null.
+    """
+
+    RESOURCE_CREATION_RESPONSE = auto()
+    """The resource creation response context.
+
+    Should be used for servers building a payload for a resource
+    creation response, and clients validating resource creation response
+    payloads.
+
+    - When used for validation, it will raise a :class:`~pydantic.ValidationError` when finding attributes annotated with :attr:`~scim2_models.Returned.never` or when attributes annotated with :attr:`~scim2_models.Returned.always` are missing or :data:`None`;
+    - When used for serialization, it will:
+        - always dump attributes annotated with :attr:`~scim2_models.Returned.always`;
+        - never dump attributes annotated with :attr:`~scim2_models.Returned.never`;
+        - dump attributes annotated with :attr:`~scim2_models.Returned.default` unless they are explicitly excluded;
+        - not dump attributes annotated with :attr:`~scim2_models.Returned.request` unless they are explicitly included.
+    """
+
+    RESOURCE_QUERY_REQUEST = auto()
+    """The resource query request context.
+
+    Should be used for clients building a payload for a resource query request,
+    and servers validating resource query request payloads.
+
+    - When used for serialization, it will not dump attributes annotated with :attr:`~scim2_models.Mutability.write_only`.
+    - When used for validation, it will raise a :class:`~pydantic.ValidationError` when finding attributes annotated with :attr:`~scim2_models.Mutability.write_only`.
+    """
+
+    RESOURCE_QUERY_RESPONSE = auto()
+    """The resource query response context.
+
+    Should be used for servers building a payload for a resource query
+    response, and clients validating resource query response payloads.
+
+    - When used for validation, it will raise a :class:`~pydantic.ValidationError` when finding attributes annotated with :attr:`~scim2_models.Returned.never` or when attributes annotated with :attr:`~scim2_models.Returned.always` are missing or :data:`None`;
+    - When used for serialization, it will:
+        - always dump attributes annotated with :attr:`~scim2_models.Returned.always`;
+        - never dump attributes annotated with :attr:`~scim2_models.Returned.never`;
+        - dump attributes annotated with :attr:`~scim2_models.Returned.default` unless they are explicitly excluded;
+        - not dump attributes annotated with :attr:`~scim2_models.Returned.request` unless they are explicitly included.
+    """
+
+    RESOURCE_REPLACEMENT_REQUEST = auto()
+    """The resource replacement request context.
+
+    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`.
+    - 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` different than the ``original`` parameter passed to :meth:`~scim2_models.BaseModel.model_validate`;
+        - when attributes annotated with :attr:`Required.true <scim2_models.Required.true>` are missing on null.
+    """
+
+    RESOURCE_REPLACEMENT_RESPONSE = auto()
+    """The resource replacement response context.
+
+    Should be used for servers building a payload for a resource
+    replacement response, and clients validating resource query
+    replacement payloads.
+
+    - When used for validation, it will raise a :class:`~pydantic.ValidationError` when finding attributes annotated with :attr:`~scim2_models.Returned.never` or when attributes annotated with :attr:`~scim2_models.Returned.always` are missing or :data:`None`;
+    - When used for serialization, it will:
+        - always dump attributes annotated with :attr:`~scim2_models.Returned.always`;
+        - never dump attributes annotated with :attr:`~scim2_models.Returned.never`;
+        - dump attributes annotated with :attr:`~scim2_models.Returned.default` unless they are explicitly excluded;
+        - not dump attributes annotated with :attr:`~scim2_models.Returned.request` unless they are explicitly included.
+    """
+
+    SEARCH_REQUEST = auto()
+    """The search request context.
+
+    Should be used for clients building a payload for a search request,
+    and servers validating search request payloads.
+
+    - When used for serialization, it will not dump attributes annotated with :attr:`~scim2_models.Mutability.write_only`.
+    - When used for validation, it will raise a :class:`~pydantic.ValidationError` when finding attributes annotated with :attr:`~scim2_models.Mutability.write_only`.
+    """
+
+    SEARCH_RESPONSE = auto()
+    """The resource query response context.
+
+    Should be used for servers building a payload for a search response,
+    and clients validating resource search payloads.
+
+    - When used for validation, it will raise a :class:`~pydantic.ValidationError` when finding attributes annotated with :attr:`~scim2_models.Returned.never` or when attributes annotated with :attr:`~scim2_models.Returned.always` are missing or :data:`None`;
+    - When used for serialization, it will:
+        - always dump attributes annotated with :attr:`~scim2_models.Returned.always`;
+        - never dump attributes annotated with :attr:`~scim2_models.Returned.never`;
+        - dump attributes annotated with :attr:`~scim2_models.Returned.default` unless they are explicitly excluded;
+        - not dump attributes annotated with :attr:`~scim2_models.Returned.request` unless they are explicitly included.
+    """
+
+    RESOURCE_PATCH_REQUEST = auto()
+    """The resource patch request context.
+
+    Should be used for clients building a payload for a PATCH request,
+    and servers validating PATCH request payloads.
+
+    - When used for serialization, it will not dump attributes annotated with :attr:`~scim2_models.Mutability.read_only`.
+    - When used for validation, it will raise a :class:`~pydantic.ValidationError`:
+        - when finding attributes annotated with :attr:`~scim2_models.Mutability.read_only`,
+        - when attributes annotated with :attr:`Required.true <scim2_models.Required.true>` are missing or null.
+    """
+
+    RESOURCE_PATCH_RESPONSE = auto()
+    """The resource patch response context.
+
+    Should be used for servers building a payload for a PATCH response,
+    and clients validating patch response payloads.
+
+    - When used for validation, it will raise a :class:`~pydantic.ValidationError` when finding attributes annotated with :attr:`~scim2_models.Returned.never` or when attributes annotated with :attr:`~scim2_models.Returned.always` are missing or :data:`None`;
+    - When used for serialization, it will:
+        - always dump attributes annotated with :attr:`~scim2_models.Returned.always`;
+        - never dump attributes annotated with :attr:`~scim2_models.Returned.never`;
+        - dump attributes annotated with :attr:`~scim2_models.Returned.default` unless they are explicitly excluded;
+        - not dump attributes annotated with :attr:`~scim2_models.Returned.request` unless they are explicitly included.
+    """
+
+    @classmethod
+    def is_request(cls, ctx: "Context") -> bool:
+        return ctx in (
+            cls.RESOURCE_CREATION_REQUEST,
+            cls.RESOURCE_QUERY_REQUEST,
+            cls.RESOURCE_REPLACEMENT_REQUEST,
+            cls.SEARCH_REQUEST,
+            cls.RESOURCE_PATCH_REQUEST,
+        )
+
+    @classmethod
+    def is_response(cls, ctx: "Context") -> bool:
+        return ctx in (
+            cls.RESOURCE_CREATION_RESPONSE,
+            cls.RESOURCE_QUERY_RESPONSE,
+            cls.RESOURCE_REPLACEMENT_RESPONSE,
+            cls.SEARCH_RESPONSE,
+            cls.RESOURCE_PATCH_RESPONSE,
+        )

scim2_models/{rfc7644 → messages}/bulk.py

@@ -6,9 +6,9 @@ from typing import Optional
 from pydantic import Field
 from pydantic import PlainSerializer
 
-from ..base import ComplexAttribute
-from ..base import Required
-from ..utils import int_to_str
+from ..annotations import Required
+from ..attributes import ComplexAttribute
+from ..utils import _int_to_str
 from .message import Message
 
 
@@ -42,7 +42,7 @@ class BulkOperation(ComplexAttribute):
     response: Optional[Any] = None
     """The HTTP response body for the specified request operation."""
 
-    status: Annotated[Optional[int], PlainSerializer(int_to_str)] = None
+    status: Annotated[Optional[int], PlainSerializer(_int_to_str)] = None
     """The HTTP response status code for the requested operation."""
 
 

scim2_models/{rfc7644 → messages}/error.py

@@ -3,8 +3,8 @@ from typing import Optional
 
 from pydantic import PlainSerializer
 
-from ..base import Required
-from ..utils import int_to_str
+from ..annotations import Required
+from ..utils import _int_to_str
 from .message import Message
 
 
@@ -15,7 +15,7 @@ class Error(Message):
         "urn:ietf:params:scim:api:messages:2.0:Error"
     ]
 
-    status: Annotated[Optional[int], PlainSerializer(int_to_str)] = None
+    status: Annotated[Optional[int], PlainSerializer(_int_to_str)] = None
     """The HTTP status code (see Section 6 of [RFC7231]) expressed as a JSON
     string."""
 
@@ -26,7 +26,7 @@ class Error(Message):
     """A detailed human-readable message."""
 
     @classmethod
-    def make_invalid_filter_error(cls):
+    def make_invalid_filter_error(cls) -> "Error":
         """Pre-defined error intended to be raised when the specified filter syntax was invalid (does not comply with :rfc:`Figure 1 of RFC7644 <7644#section-3.4.2.2>`), or the specified attribute and filter comparison combination is not supported."""
         return Error(
             status=400,
@@ -35,7 +35,7 @@ class Error(Message):
         )
 
     @classmethod
-    def make_too_many_error(cls):
+    def make_too_many_error(cls) -> "Error":
         """Pre-defined error intended to be raised when the specified filter yields many more results than the server is willing to calculate or process.  For example, a filter such as ``(userName pr)`` by itself would return all entries with a ``userName`` and MAY not be acceptable to the service provider."""
         return Error(
             status=400,
@@ -44,7 +44,7 @@ class Error(Message):
         )
 
     @classmethod
-    def make_uniqueness_error(cls):
+    def make_uniqueness_error(cls) -> "Error":
         """Pre-defined error intended to be raised when One or more of the attribute values are already in use or are reserved."""
         return Error(
             status=409,
@@ -53,7 +53,7 @@ class Error(Message):
         )
 
     @classmethod
-    def make_mutability_error(cls):
+    def make_mutability_error(cls) -> "Error":
         """Pre-defined error intended to be raised when the attempted modification is not compatible with the target attribute's mutability or current state (e.g., modification of an "immutable" attribute with an existing value)."""
         return Error(
             status=400,
@@ -62,7 +62,7 @@ class Error(Message):
         )
 
     @classmethod
-    def make_invalid_syntax_error(cls):
+    def make_invalid_syntax_error(cls) -> "Error":
         """Pre-defined error intended to be raised when the request body message structure was invalid or did not conform to the request schema."""
         return Error(
             status=400,
@@ -71,7 +71,7 @@ class Error(Message):
         )
 
     @classmethod
-    def make_invalid_path_error(cls):
+    def make_invalid_path_error(cls) -> "Error":
         """Pre-defined error intended to be raised when the "path" attribute was invalid or malformed (see :rfc:`Figure 7 of RFC7644 <7644#section-3.5.2>`)."""
         return Error(
             status=400,
@@ -80,7 +80,7 @@ class Error(Message):
         )
 
     @classmethod
-    def make_no_target_error(cls):
+    def make_no_target_error(cls) -> "Error":
         """Pre-defined error intended to be raised when the specified "path" did not yield an attribute or attribute value that could be operated on.  This occurs when the specified "path" value contains a filter that yields no match."""
         return Error(
             status=400,
@@ -89,7 +89,7 @@ class Error(Message):
         )
 
     @classmethod
-    def make_invalid_value_error(cls):
+    def make_invalid_value_error(cls) -> "Error":
         """Pre-defined error intended to be raised when a required value was missing, or the value specified was not compatible with the operation or attribute type (see :rfc:`Section 2.2 of RFC7643 <7643#section-2.2>`), or resource schema (see :rfc:`Section 4 of RFC7643 <7643#section-4>`)."""
         return Error(
             status=400,
@@ -98,7 +98,7 @@ class Error(Message):
         )
 
     @classmethod
-    def make_invalid_version_error(cls):
+    def make_invalid_version_error(cls) -> "Error":
         """Pre-defined error intended to be raised when the specified SCIM protocol version is not supported (see :rfc:`Section 3.13 of RFC7644 <7644#section-3.13>`)."""
         return Error(
             status=400,
@@ -107,7 +107,7 @@ class Error(Message):
         )
 
     @classmethod
-    def make_sensitive_error(cls):
+    def make_sensitive_error(cls) -> "Error":
         """Pre-defined error intended to be raised when the specified request cannot be completed, due to the passing of sensitive (e.g., personal) information in a request URI.  For example, personal information SHALL NOT be transmitted over request URIs.  See :rfc:`Section 7.5.2 of RFC7644 <7644#section-7.5.2>`."""
         return Error(
             status=400,

scim2_models/messages/list_response.py

@@ -0,0 +1,75 @@
+from typing import Annotated
+from typing import Any
+from typing import Generic
+from typing import Optional
+
+from pydantic import Field
+from pydantic import ValidationInfo
+from pydantic import ValidatorFunctionWrapHandler
+from pydantic import model_validator
+from pydantic_core import PydanticCustomError
+from typing_extensions import Self
+
+from ..annotations import Required
+from ..context import Context
+from ..resources.resource import AnyResource
+from .message import Message
+from .message import _GenericMessageMetaclass
+
+
+class ListResponse(Message, Generic[AnyResource], metaclass=_GenericMessageMetaclass):
+    schemas: Annotated[list[str], Required.true] = [
+        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
+    ]
+
+    total_results: Optional[int] = None
+    """The total number of results returned by the list or query operation."""
+
+    start_index: Optional[int] = None
+    """The 1-based index of the first result in the current set of list
+    results."""
+
+    items_per_page: Optional[int] = None
+    """The number of resources returned in a list response page."""
+
+    resources: Optional[list[AnyResource]] = Field(
+        None, serialization_alias="Resources"
+    )
+    """A multi-valued list of complex objects containing the requested
+    resources."""
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def check_results_number(
+        cls, value: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo
+    ) -> Self:
+        """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)
+        assert isinstance(obj, cls)
+
+        if (
+            not info.context
+            or not info.context.get("scim")
+            or not Context.is_response(info.context["scim"])
+        ):
+            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",
+                "Field 'resources' is missing or null but 'total_results' is non-zero.",
+            )
+
+        return obj

scim2_models/messages/message.py

@@ -0,0 +1,119 @@
+from typing import Annotated
+from typing import Any
+from typing import Callable
+from typing import Optional
+from typing import Union
+from typing import get_args
+from typing import get_origin
+
+from pydantic import Discriminator
+from pydantic import Tag
+from pydantic._internal._model_construction import ModelMetaclass
+
+from scim2_models.resources.resource import Resource
+
+from ..base import BaseModel
+from ..scim_object import ScimObject
+from ..utils import UNION_TYPES
+
+
+class Message(ScimObject):
+    """SCIM protocol messages as defined by :rfc:`RFC7644 §3.1 <7644#section-3.1>`."""
+
+
+def _create_schema_discriminator(
+    resource_types_schemas: list[str],
+) -> Callable[[Any], Optional[str]]:
+    """Create a schema discriminator function for the given resource schemas.
+
+    :param resource_types_schemas: List of valid resource schemas
+    :return: Discriminator function for Pydantic
+    """
+
+    def get_schema_from_payload(payload: Any) -> Optional[str]:
+        """Extract schema from SCIM payload for discrimination.
+
+        :param payload: SCIM payload dict or object
+        :return: First matching schema or None
+        """
+        if not payload:
+            return None
+
+        payload_schemas = (
+            payload.get("schemas", []) if isinstance(payload, dict) else payload.schemas
+        )
+
+        common_schemas = [
+            schema for schema in payload_schemas if schema in resource_types_schemas
+        ]
+        return common_schemas[0] if common_schemas else None
+
+    return get_schema_from_payload
+
+
+def _get_tag(resource_type: type[BaseModel]) -> Tag:
+    """Create Pydantic tag from resource type schema.
+
+    :param resource_type: SCIM resource type
+    :return: Pydantic Tag for discrimination
+    """
+    return Tag(resource_type.model_fields["schemas"].default[0])
+
+
+def _create_tagged_resource_union(resource_union: Any) -> Any:
+    """Build Discriminated Unions for SCIM resources.
+
+    Creates discriminated unions so Pydantic can determine which class to instantiate
+    by inspecting the payload's schemas field.
+
+    :param resource_union: Union type of SCIM resources
+    :return: Annotated discriminated union or original type
+    """
+    if get_origin(resource_union) not in UNION_TYPES:
+        return resource_union
+
+    resource_types = get_args(resource_union)
+
+    # Set up schemas for the discriminator function
+    resource_types_schemas = [
+        resource_type.model_fields["schemas"].default[0]
+        for resource_type in resource_types
+    ]
+
+    # Create discriminator function with schemas captured in closure
+    schema_discriminator = _create_schema_discriminator(resource_types_schemas)
+    discriminator = Discriminator(schema_discriminator)
+
+    tagged_resources = [
+        Annotated[resource_type, _get_tag(resource_type)]
+        for resource_type in resource_types
+    ]
+    # Dynamic union construction from tuple - MyPy can't validate this at compile time
+    union = Union[tuple(tagged_resources)]  # type: ignore
+    return Annotated[union, discriminator]
+
+
+class _GenericMessageMetaclass(ModelMetaclass):
+    """Metaclass for SCIM generic types with discriminated unions."""
+
+    def __new__(
+        cls, name: str, bases: tuple[type, ...], attrs: dict[str, Any], **kwargs: Any
+    ) -> type:
+        """Create class with tagged resource unions for generic parameters."""
+        if kwargs.get("__pydantic_generic_metadata__") and kwargs[
+            "__pydantic_generic_metadata__"
+        ].get("args"):
+            tagged_union = _create_tagged_resource_union(
+                kwargs["__pydantic_generic_metadata__"]["args"][0]
+            )
+            kwargs["__pydantic_generic_metadata__"]["args"] = (tagged_union,)
+
+        klass = super().__new__(cls, name, bases, attrs, **kwargs)
+        return klass
+
+
+def _get_resource_class(obj) -> Optional[type[Resource]]:
+    """Extract the resource class from generic type parameter."""
+    metadata = getattr(obj.__class__, "__pydantic_generic_metadata__", {"args": [None]})
+    resource_class = metadata["args"][0]
+    return resource_class