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

scim2_models/reference.py

@@ -1,80 +1,171 @@
-from collections import UserString
+import warnings
 from typing import Any
 from typing import Generic
-from typing import NewType
+from typing import Literal
 from typing import TypeVar
 from typing import get_args
 from typing import get_origin
 
 from pydantic import GetCoreSchemaHandler
+from pydantic_core import Url
+from pydantic_core import ValidationError
 from pydantic_core import core_schema
 
 from .utils import UNION_TYPES
 
 ReferenceTypes = TypeVar("ReferenceTypes")
 
-URIReference = NewType("URIReference", str)
-ExternalReference = NewType("ExternalReference", str)
 
+class External:
+    """Marker for external references per :rfc:`RFC7643 §7 <7643#section-7>`.
 
-class Reference(UserString, Generic[ReferenceTypes]):
+    Use with :class:`Reference` to type external resource URLs (photos, websites)::
+
+        profile_url: Reference[External] | None = None
+    """
+
+
+class URI:
+    """Marker for URI references per :rfc:`RFC7643 §7 <7643#section-7>`.
+
+    Use with :class:`Reference` to type URI identifiers (schema URNs, endpoints)::
+
+        endpoint: Reference[URI] | None = None
+    """
+
+
+class ExternalReference:
+    """Deprecated. Use :class:`External` instead."""
+
+
+class URIReference:
+    """Deprecated. Use :class:`URI` instead."""
+
+
+class Reference(str, 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
-    --------
+    - :class:`~scim2_models.External` for external resources (photos, websites)
+    - :class:`~scim2_models.URI` for URI identifiers (schema URNs, endpoints)
+    - String forward references for SCIM resource types (``"User"``, ``"Group"``)
+    - Resource classes directly if imports allow
 
-    .. code-block:: python
+    Examples::
 
         class Foobar(Resource):
-            bff: Reference[User]
-            managers: Reference[Union["User", "Group"]]
-            photo: Reference[ExternalReference]
-            website: Reference[URIReference]
-
+            photo: Reference[External] | None = None
+            website: Reference[URI] | None = None
+            manager: Reference["User"] | None = None
+            members: Reference[Union["User", "Group"]] | None = None
+
+    .. versionchanged:: 0.6.0
+
+        - ``Reference[ExternalReference]`` becomes ``Reference[External]``
+        - ``Reference[URIReference]`` becomes ``Reference[URI]``
+        - ``Reference[Literal["User"]]`` becomes ``Reference["User"]``
+        - ``Reference[Literal["User"] | Literal["Group"]]`` becomes
+          ``Reference[Union["User", "Group"]]``
     """
 
+    __slots__ = ()
+    __reference_types__: tuple[str, ...] = ()
+    _cache: dict[tuple[str, ...], type["Reference[Any]"]] = {}
+
+    def __class_getitem__(cls, item: Any) -> type["Reference[Any]"]:
+        if get_origin(item) in UNION_TYPES:
+            items = get_args(item)
+        else:
+            items = (item,)
+
+        type_strings = tuple(_to_type_string(i) for i in items)
+
+        if type_strings in cls._cache:
+            return cls._cache[type_strings]
+
+        class TypedReference(cls):  # type: ignore[valid-type,misc]
+            __reference_types__ = type_strings
+
+        TypedReference.__name__ = f"Reference[{' | '.join(type_strings)}]"
+        TypedReference.__qualname__ = TypedReference.__name__
+        cls._cache[type_strings] = TypedReference
+        return TypedReference
+
     @classmethod
     def __get_pydantic_core_schema__(
         cls,
-        _source: type[Any],
-        _handler: GetCoreSchemaHandler,
+        source_type: 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)]
-            ),
+        ref_types = getattr(source_type, "__reference_types__", ())
+
+        def validate(value: Any) -> "Reference[Any]":
+            if not isinstance(value, str):
+                raise ValueError(f"Expected string, got {type(value).__name__}")
+            if "external" in ref_types or "uri" in ref_types:
+                _validate_uri(value)
+            return source_type(value)  # type: ignore[no-any-return]
+
+        return core_schema.no_info_plain_validator_function(
+            validate,
+            serialization=core_schema.plain_serializer_function_ser_schema(str),
         )
 
     @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
-        :return: List of reference type strings
-        """
-        first_arg = get_args(type_annotation)[0]
-        types = (
-            get_args(first_arg) if get_origin(first_arg) in UNION_TYPES else [first_arg]
+    def get_scim_reference_types(cls) -> list[str]:
+        """Return referenceTypes for SCIM schema generation."""
+        return list(cls.__reference_types__)
+
+
+def _to_type_string(item: Any) -> str:
+    """Convert any type parameter to its SCIM referenceType string."""
+    if item is Any:
+        return "uri"
+    if item is External:
+        return "external"
+    if item is ExternalReference:
+        warnings.warn(
+            "Reference[ExternalReference] is deprecated, "
+            "use Reference[External] instead. Will be removed in 0.7.0.",
+            DeprecationWarning,
+            stacklevel=4,
         )
-
-        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))
+        return "external"
+    if item is URI:
+        return "uri"
+    if item is URIReference:
+        warnings.warn(
+            "Reference[URIReference] is deprecated, "
+            "use Reference[URI] instead. Will be removed in 0.7.0.",
+            DeprecationWarning,
+            stacklevel=4,
+        )
+        return "uri"
+    if isinstance(item, str):
+        return item
+    if isinstance(item, type):
+        return item.__name__
+    if hasattr(item, "__forward_arg__"):
+        return item.__forward_arg__  # type: ignore[no-any-return]
+    # Support Literal["User"] for backwards compatibility
+    if get_origin(item) is Literal:
+        value = get_args(item)[0]
+        warnings.warn(
+            f'Reference[Literal["{value}"]] is deprecated, '
+            f'use Reference["{value}"] instead. Will be removed in 0.7.0.',
+            DeprecationWarning,
+            stacklevel=4,
+        )
+        return value  # type: ignore[no-any-return]
+    raise TypeError(f"Invalid reference type: {item!r}")
+
+
+def _validate_uri(value: str) -> None:
+    """Validate URI format, allowing relative URIs per RFC 7643."""
+    if value.startswith("/"):
+        return
+    try:
+        Url(value)
+    except ValidationError as e:
+        raise ValueError(f"Invalid URI: {value}") from e

scim2_models/resources/enterprise_user.py

@@ -1,23 +1,27 @@
+from typing import TYPE_CHECKING
 from typing import Annotated
-from typing import Literal
 
 from pydantic import Field
 
 from ..annotations import Mutability
 from ..annotations import Required
 from ..attributes import ComplexAttribute
+from ..path import URN
 from ..reference import Reference
 from .resource import Extension
 
+if TYPE_CHECKING:
+    from .user import User
+
 
 class Manager(ComplexAttribute):
     value: Annotated[str | None, Required.true] = None
     """The id of the SCIM resource representing the User's manager."""
 
-    ref: Annotated[Reference[Literal["User"]] | None, Required.true] = Field(
-        None,
-        serialization_alias="$ref",
-    )
+    ref: Annotated[  # type: ignore[type-arg]
+        Reference["User"] | None,
+        Required.true,
+    ] = Field(None, serialization_alias="$ref")
     """The URI of the SCIM resource representing the User's manager."""
 
     display_name: Annotated[str | None, Mutability.read_only] = None
@@ -25,9 +29,7 @@ class Manager(ComplexAttribute):
 
 
 class EnterpriseUser(Extension):
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:schemas:extension:enterprise:2.0:User")
 
     employee_number: str | None = None
     """Numeric or alphanumeric identifier assigned to a person, typically based

scim2_models/resources/group.py

@@ -1,23 +1,27 @@
+from typing import TYPE_CHECKING
 from typing import Annotated
 from typing import Any
 from typing import ClassVar
-from typing import Literal
+from typing import Union
 
 from pydantic import Field
 
 from ..annotations import Mutability
-from ..annotations import Required
 from ..attributes import ComplexAttribute
+from ..path import URN
 from ..reference import Reference
 from .resource import Resource
 
+if TYPE_CHECKING:
+    from .user import User
+
 
 class GroupMember(ComplexAttribute):
     value: Annotated[str | None, Mutability.immutable] = None
     """Identifier of the member of this Group."""
 
-    ref: Annotated[
-        Reference[Literal["User"] | Literal["Group"]] | None,
+    ref: Annotated[  # type: ignore[type-arg]
+        Reference[Union["User", "Group"]] | None,
         Mutability.immutable,
     ] = Field(None, serialization_alias="$ref")
     """The reference URI of a target resource, if the attribute is a
@@ -32,9 +36,7 @@ class GroupMember(ComplexAttribute):
 
 
 class Group(Resource[Any]):
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:schemas:core:2.0:Group"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:schemas:core:2.0:Group")
 
     display_name: str | None = None
     """A human-readable name for the Group."""

scim2_models/resources/resource.py

@@ -5,15 +5,19 @@ from typing import Any
 from typing import Generic
 from typing import TypeVar
 from typing import Union
-from typing import cast
 from typing import get_args
 from typing import get_origin
 
 from pydantic import Field
 from pydantic import SerializationInfo
 from pydantic import SerializerFunctionWrapHandler
+from pydantic import ValidationInfo
+from pydantic import ValidatorFunctionWrapHandler
 from pydantic import WrapSerializer
 from pydantic import field_serializer
+from pydantic import model_validator
+from pydantic_core import PydanticCustomError
+from typing_extensions import Self
 
 from ..annotations import CaseExact
 from ..annotations import Mutability
@@ -24,9 +28,9 @@ from ..attributes import ComplexAttribute
 from ..attributes import is_complex_attribute
 from ..base import BaseModel
 from ..context import Context
-from ..reference import Reference
+from ..exceptions import InvalidPathException
+from ..path import Path
 from ..scim_object import ScimObject
-from ..urn import _validate_attribute_urn
 from ..utils import UNION_TYPES
 from ..utils import _normalize_attribute_name
 
@@ -178,7 +182,7 @@ class Resource(ScimObject, Generic[AnyExtension]):
         class_attrs = {"__scim_extension_metadata__": valid_extensions}
 
         for extension in valid_extensions:
-            schema = extension.model_fields["schemas"].default[0]
+            schema = extension.__schema__
             class_attrs[extension.__name__] = Field(
                 default=None,  # type: ignore[arg-type]
                 serialization_alias=schema,
@@ -206,24 +210,79 @@ class Resource(ScimObject, Generic[AnyExtension]):
 
         return new_class
 
-    def __getitem__(self, item: Any) -> Extension | None:
-        if not isinstance(item, type) or not issubclass(item, Extension):
-            raise KeyError(f"{item} is not a valid extension type")
+    def __getitem__(self, item: Any) -> Any:
+        """Get a value by extension type or path.
 
-        return cast(Extension | None, getattr(self, item.__name__))
+        :param item: An Extension subclass or a path (string or Path).
+        :returns: The extension instance or the value at the path.
+        :raises KeyError: If the path references a non-existent field.
 
-    def __setitem__(self, item: Any, value: "Extension") -> None:
-        if not isinstance(item, type) or not issubclass(item, Extension):
-            raise KeyError(f"{item} is not a valid extension type")
+        Examples::
 
-        setattr(self, item.__name__, value)
+            user[EnterpriseUser]  # Get extension
+            user["userName"]  # Get attribute
+            user["name.familyName"]  # Get nested attribute
+        """
+        if isinstance(item, type) and issubclass(item, Extension):
+            item = item.__schema__
+
+        bound_path = Path.__class_getitem__(type(self))
+        path = item if isinstance(item, Path) else bound_path(str(item))
+        try:
+            return path.get(self)
+        except InvalidPathException as exc:
+            raise KeyError(str(item)) from exc
+
+    def __setitem__(self, item: Any, value: Any) -> None:
+        """Set a value by extension type or path.
+
+        :param item: An Extension subclass or a path (string or Path).
+        :param value: The value to set.
+        :raises KeyError: If the path references a non-existent field.
+
+        Examples::
+
+            user[EnterpriseUser] = EnterpriseUser(employee_number="123")
+            user["displayName"] = "John Doe"
+            user["name.familyName"] = "Doe"
+        """
+        if isinstance(item, type) and issubclass(item, Extension):
+            item = item.__schema__
+
+        bound_path = Path.__class_getitem__(type(self))
+        path = item if isinstance(item, Path) else bound_path(str(item))
+        try:
+            path.set(self, value)
+        except InvalidPathException as exc:
+            raise KeyError(str(item)) from exc
+
+    def __delitem__(self, item: Any) -> None:
+        """Delete a value by extension type or path.
+
+        :param item: An Extension subclass or a path (string or Path).
+        :raises KeyError: If the path references a non-existent field.
+
+        Examples::
+
+            del user[EnterpriseUser]  # Remove extension
+            del user["displayName"]  # Remove attribute
+        """
+        if isinstance(item, type) and issubclass(item, Extension):
+            item = item.__schema__
+
+        bound_path = Path.__class_getitem__(type(self))
+        path = item if isinstance(item, Path) else bound_path(str(item))
+        try:
+            path.delete(self)
+        except InvalidPathException as exc:
+            raise KeyError(str(item)) from exc
 
     @classmethod
     def get_extension_models(cls) -> dict[str, type[Extension]]:
         """Return extension a dict associating extension models with their schemas."""
         extension_models = getattr(cls, "__scim_extension_metadata__", [])
-        by_schema = {
-            ext.model_fields["schemas"].default[0]: ext for ext in extension_models
+        by_schema: dict[str, type[Extension]] = {
+            ext.__schema__: ext for ext in extension_models
         }
         return by_schema
 
@@ -245,7 +304,7 @@ class Resource(ScimObject, Generic[AnyExtension]):
     ) -> type["Resource[Any]"] | type["Extension"] | None:
         """Given a resource type list and a schema, find the matching resource type."""
         by_schema: dict[str, type[Resource[Any]] | type[Extension]] = {
-            resource_type.model_fields["schemas"].default[0].lower(): resource_type
+            getattr(resource_type, "__schema__", "").lower(): resource_type
             for resource_type in (resource_types or [])
         }
         if with_extensions:
@@ -283,6 +342,35 @@ class Resource(ScimObject, Generic[AnyExtension]):
         ]
         return schemas
 
+    @model_validator(mode="wrap")
+    @classmethod
+    def _validate_extension_schemas(
+        cls, value: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo
+    ) -> Self:
+        """Validate that extension schemas are known."""
+        obj: Self = handler(value)
+
+        scim_ctx = info.context.get("scim") if info.context else None
+        if scim_ctx is None or scim_ctx == Context.DEFAULT:
+            return obj
+
+        base_schema = getattr(cls, "__schema__", None)
+        if not base_schema:
+            return obj
+
+        allowed_extensions = set(cls.get_extension_models().keys())
+        provided_schemas = set(obj.schemas) - {base_schema}
+
+        unknown = provided_schemas - allowed_extensions
+        if unknown:
+            raise PydanticCustomError(
+                "unknown_extension_schema",
+                "Unknown extension schemas: {schemas}",
+                {"schemas": ", ".join(sorted(unknown))},
+            )
+
+        return obj
+
     @classmethod
     def to_schema(cls) -> "Schema":
         """Build a :class:`~scim2_models.Schema` from the current resource class."""
@@ -305,17 +393,16 @@ class Resource(ScimObject, Generic[AnyExtension]):
         kwargs = super()._prepare_model_dump(scim_ctx, **kwargs)
 
         # RFC 7644: "SHOULD ignore any query parameters they do not recognize"
+        bound_path = Path.__class_getitem__(type(self))
         kwargs["context"]["scim_attributes"] = [
-            valid_attr
+            urn
             for attribute in (attributes or [])
-            if (valid_attr := _validate_attribute_urn(attribute, self.__class__))
-            is not None
+            if (urn := bound_path(attribute).urn) is not None
         ]
         kwargs["context"]["scim_excluded_attributes"] = [
-            valid_attr
+            urn
             for attribute in (excluded_attributes or [])
-            if (valid_attr := _validate_attribute_urn(attribute, self.__class__))
-            is not None
+            if (urn := bound_path(attribute).urn) is not None
         ]
         return kwargs
 
@@ -404,7 +491,7 @@ def _dedicated_attributes(
 def _model_to_schema(model: type[BaseModel]) -> "Schema":
     from scim2_models.resources.schema import Schema
 
-    schema_urn = model.model_fields["schemas"].default[0]
+    schema_urn = getattr(model, "__schema__", "") or ""
     field_infos = _dedicated_attributes(model, [Resource])
     attributes = [
         _model_attribute_to_scim_attribute(model, attribute_name)
@@ -457,7 +544,7 @@ def _model_attribute_to_scim_attribute(
         returned=model.get_field_annotation(attribute_name, Returned),
         uniqueness=model.get_field_annotation(attribute_name, Uniqueness),
         sub_attributes=sub_attributes,
-        reference_types=Reference.get_types(root_type)
+        reference_types=root_type.get_scim_reference_types()  # type: ignore[attr-defined]
         if attribute_type == Attribute.Type.reference
         else None,
     )

scim2_models/resources/resource_type.py

@@ -9,14 +9,15 @@ from ..annotations import Mutability
 from ..annotations import Required
 from ..annotations import Returned
 from ..attributes import ComplexAttribute
+from ..path import URN
+from ..reference import URI
 from ..reference import Reference
-from ..reference import URIReference
 from .resource import Resource
 
 
 class SchemaExtension(ComplexAttribute):
     schema_: Annotated[
-        Reference[URIReference] | None,
+        Reference[URI] | None,
         Mutability.read_only,
         Required.true,
         CaseExact.true,
@@ -35,9 +36,7 @@ class SchemaExtension(ComplexAttribute):
 
 
 class ResourceType(Resource[Any]):
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:schemas:core:2.0:ResourceType")
 
     name: Annotated[str | None, Mutability.read_only, Required.true] = None
     """The resource type name.
@@ -58,14 +57,14 @@ class ResourceType(Resource[Any]):
     This is often the same value as the "name" attribute.
     """
 
-    endpoint: Annotated[
-        Reference[URIReference] | None, Mutability.read_only, Required.true
-    ] = None
+    endpoint: Annotated[Reference[URI] | None, Mutability.read_only, Required.true] = (
+        None
+    )
     """The resource type's HTTP-addressable endpoint relative to the Base URL,
     e.g., '/Users'."""
 
     schema_: Annotated[
-        Reference[URIReference] | None,
+        Reference[URI] | None,
         Mutability.read_only,
         Required.true,
         CaseExact.true,
@@ -80,21 +79,23 @@ class ResourceType(Resource[Any]):
     @classmethod
     def from_resource(cls, resource_model: type[Resource[Any]]) -> Self:
         """Build a naive ResourceType from a resource model."""
-        schema = resource_model.model_fields["schemas"].default[0]
+        schema = resource_model.__schema__
+        if schema is None:
+            raise ValueError(f"{resource_model.__name__} has no __schema__ defined")
         name = schema.split(":")[-1]
 
-        # Get extensions from the metadata system
         extensions = getattr(resource_model, "__scim_extension_metadata__", [])
 
         return cls(
             id=name,
             name=name,
             description=name,
-            endpoint=Reference[URIReference](f"/{name}s"),
-            schema_=schema,
+            endpoint=Reference[URI](f"/{name}s"),
+            schema_=Reference[URI](schema),
             schema_extensions=[
                 SchemaExtension(
-                    schema_=extension.model_fields["schemas"].default[0], required=False
+                    schema_=Reference[URI](extension.__schema__),
+                    required=False,
                 )
                 for extension in extensions
             ],