scim2-models 0.3.5__py3-none-any.whl → 0.3.7__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 :paramref:`~scim2_models.BaseModel.model_validate.original`:
+        - 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/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/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
 
 

scim2_models/rfc7643/group.py

@@ -6,11 +6,11 @@ from typing import Union
 
 from pydantic import Field
 
-from ..base import ComplexAttribute
-from ..base import MultiValuedComplexAttribute
-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 ..attributes import MultiValuedComplexAttribute
+from ..reference import Reference
 from .resource import Resource