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

scim2_models/resources/user.py

@@ -2,8 +2,6 @@ from enum import Enum
 from typing import Annotated
 from typing import ClassVar
 from typing import Literal
-from typing import Optional
-from typing import Union
 
 from pydantic import EmailStr
 from pydantic import Field
@@ -14,7 +12,6 @@ from ..annotations import Required
 from ..annotations import Returned
 from ..annotations import Uniqueness
 from ..attributes import ComplexAttribute
-from ..attributes import MultiValuedComplexAttribute
 from ..reference import ExternalReference
 from ..reference import Reference
 from ..utils import Base64Bytes
@@ -23,53 +20,53 @@ from .resource import Resource
 
 
 class Name(ComplexAttribute):
-    formatted: Optional[str] = None
+    formatted: str | None = None
     """The full name, including all middle names, titles, and suffixes as
     appropriate, formatted for display (e.g., 'Ms. Barbara J Jensen, III')."""
 
-    family_name: Optional[str] = None
+    family_name: str | None = None
     """The family name of the User, or last name in most Western languages
     (e.g., 'Jensen' given the full name 'Ms. Barbara J Jensen, III')."""
 
-    given_name: Optional[str] = None
+    given_name: str | None = None
     """The given name of the User, or first name in most Western languages
     (e.g., 'Barbara' given the full name 'Ms. Barbara J Jensen, III')."""
 
-    middle_name: Optional[str] = None
+    middle_name: str | None = None
     """The middle name(s) of the User (e.g., 'Jane' given the full name 'Ms.
     Barbara J Jensen, III')."""
 
-    honorific_prefix: Optional[str] = None
+    honorific_prefix: str | None = None
     """The honorific prefix(es) of the User, or title in most Western languages
     (e.g., 'Ms.' given the full name 'Ms. Barbara J Jensen, III')."""
 
-    honorific_suffix: Optional[str] = None
+    honorific_suffix: str | None = None
     """The honorific suffix(es) of the User, or suffix in most Western
     languages (e.g., 'III' given the full name 'Ms. Barbara J Jensen, III')."""
 
 
-class Email(MultiValuedComplexAttribute):
+class Email(ComplexAttribute):
     class Type(str, Enum):
         work = "work"
         home = "home"
         other = "other"
 
-    value: Optional[EmailStr] = None
+    value: EmailStr | None = None
     """Email addresses for the user."""
 
-    display: Optional[str] = None
+    display: str | None = None
     """A human-readable name, primarily used for display purposes."""
 
-    type: Optional[Type] = Field(None, examples=["work", "home", "other"])
+    type: Type | None = Field(None, examples=["work", "home", "other"])
     """A label indicating the attribute's function, e.g., 'work' or 'home'."""
 
-    primary: Optional[bool] = None
+    primary: bool | None = None
     """A Boolean value indicating the 'primary' or preferred attribute value
     for this attribute, e.g., the preferred mailing address or primary email
     address."""
 
 
-class PhoneNumber(MultiValuedComplexAttribute):
+class PhoneNumber(ComplexAttribute):
     class Type(str, Enum):
         work = "work"
         home = "home"
@@ -78,25 +75,25 @@ class PhoneNumber(MultiValuedComplexAttribute):
         pager = "pager"
         other = "other"
 
-    value: Optional[str] = None
+    value: str | None = None
     """Phone number of the User."""
 
-    display: Optional[str] = None
+    display: str | None = None
     """A human-readable name, primarily used for display purposes."""
 
-    type: Optional[Type] = Field(
+    type: Type | None = Field(
         None, examples=["work", "home", "mobile", "fax", "pager", "other"]
     )
     """A label indicating the attribute's function, e.g., 'work', 'home',
     'mobile'."""
 
-    primary: Optional[bool] = None
+    primary: bool | None = None
     """A Boolean value indicating the 'primary' or preferred attribute value
     for this attribute, e.g., the preferred phone number or primary phone
     number."""
 
 
-class Im(MultiValuedComplexAttribute):
+class Im(ComplexAttribute):
     class Type(str, Enum):
         aim = "aim"
         gtalk = "gtalk"
@@ -107,214 +104,246 @@ class Im(MultiValuedComplexAttribute):
         qq = "qq"
         yahoo = "yahoo"
 
-    value: Optional[str] = None
+    value: str | None = None
     """Instant messaging address for the User."""
 
-    display: Optional[str] = None
+    display: str | None = None
     """A human-readable name, primarily used for display purposes."""
 
-    type: Optional[Type] = Field(
+    type: Type | None = Field(
         None, examples=["aim", "gtalk", "icq", "xmpp", "msn", "skype", "qq", "yahoo"]
     )
     """A label indicating the attribute's function, e.g., 'aim', 'gtalk',
     'xmpp'."""
 
-    primary: Optional[bool] = None
+    primary: bool | None = None
     """A Boolean value indicating the 'primary' or preferred attribute value
     for this attribute, e.g., the preferred messenger or primary messenger."""
 
 
-class Photo(MultiValuedComplexAttribute):
+class Photo(ComplexAttribute):
     class Type(str, Enum):
         photo = "photo"
         thumbnail = "thumbnail"
 
-    value: Annotated[Optional[Reference[ExternalReference]], CaseExact.true] = None
+    value: Annotated[Reference[ExternalReference] | None, CaseExact.true] = None
     """URL of a photo of the User."""
 
-    display: Optional[str] = None
+    display: str | None = None
     """A human-readable name, primarily used for display purposes."""
 
-    type: Optional[Type] = Field(None, examples=["photo", "thumbnail"])
+    type: Type | None = Field(None, examples=["photo", "thumbnail"])
     """A label indicating the attribute's function, i.e., 'photo' or
     'thumbnail'."""
 
-    primary: Optional[bool] = None
+    primary: bool | None = None
     """A Boolean value indicating the 'primary' or preferred attribute value
     for this attribute, e.g., the preferred photo or thumbnail."""
 
 
-class Address(MultiValuedComplexAttribute):
+class Address(ComplexAttribute):
     class Type(str, Enum):
         work = "work"
         home = "home"
         other = "other"
 
-    formatted: Optional[str] = None
+    formatted: str | None = None
     """The full mailing address, formatted for display or use with a mailing
     label."""
 
-    street_address: Optional[str] = None
+    street_address: str | None = None
     """The full street address component, which may include house number,
     street name, P.O.
 
     box, and multi-line extended street address information.
     """
 
-    locality: Optional[str] = None
+    locality: str | None = None
     """The city or locality component."""
 
-    region: Optional[str] = None
+    region: str | None = None
     """The state or region component."""
 
-    postal_code: Optional[str] = None
+    postal_code: str | None = None
     """The zip code or postal code component."""
 
-    country: Optional[str] = None
+    country: str | None = None
     """The country name component."""
 
-    type: Optional[Type] = Field(None, examples=["work", "home", "other"])
+    type: Type | None = Field(None, examples=["work", "home", "other"])
     """A label indicating the attribute's function, e.g., 'work' or 'home'."""
 
-    primary: Optional[bool] = None
+    primary: bool | None = None
     """A Boolean value indicating the 'primary' or preferred attribute value
     for this attribute, e.g., the preferred photo or thumbnail."""
 
 
-class Entitlement(MultiValuedComplexAttribute):
-    pass
+class Entitlement(ComplexAttribute):
+    value: str | None = None
+    """The value of an entitlement."""
 
+    display: str | None = None
+    """A human-readable name, primarily used for display purposes."""
+
+    type: str | None = None
+    """A label indicating the attribute's function."""
+
+    primary: bool | None = None
+    """A Boolean value indicating the 'primary' or preferred attribute value
+    for this attribute."""
 
-class GroupMembership(MultiValuedComplexAttribute):
-    value: Annotated[Optional[str], Mutability.read_only] = None
+
+class GroupMembership(ComplexAttribute):
+    value: Annotated[str | None, Mutability.read_only] = None
     """The identifier of the User's group."""
 
     ref: Annotated[
-        Optional[Reference[Union[Literal["User"], Literal["Group"]]]],
+        Reference[Literal["User"] | Literal["Group"]] | None,
         Mutability.read_only,
     ] = Field(None, serialization_alias="$ref")
     """The reference URI of a target resource, if the attribute is a
     reference."""
 
-    display: Annotated[Optional[str], Mutability.read_only] = None
+    display: Annotated[str | None, Mutability.read_only] = None
     """A human-readable name, primarily used for display purposes."""
 
-    type: Annotated[Optional[str], Mutability.read_only] = Field(
+    type: Annotated[str | None, Mutability.read_only] = Field(
         None, examples=["direct", "indirect"]
     )
     """A label indicating the attribute's function, e.g., 'direct' or
     'indirect'."""
 
 
-class Role(MultiValuedComplexAttribute):
-    pass
+class Role(ComplexAttribute):
+    value: str | None = None
+    """The value of a role."""
+
+    display: str | None = None
+    """A human-readable name, primarily used for display purposes."""
 
+    type: str | None = None
+    """A label indicating the attribute's function."""
 
-class X509Certificate(MultiValuedComplexAttribute):
-    value: Annotated[Optional[Base64Bytes], CaseExact.true] = None
+    primary: bool | None = None
+    """A Boolean value indicating the 'primary' or preferred attribute value
+    for this attribute."""
+
+
+class X509Certificate(ComplexAttribute):
+    value: Annotated[Base64Bytes | None, CaseExact.true] = None
     """The value of an X.509 certificate."""
 
+    display: str | None = None
+    """A human-readable name, primarily used for display purposes."""
+
+    type: str | None = None
+    """A label indicating the attribute's function."""
+
+    primary: bool | None = None
+    """A Boolean value indicating the 'primary' or preferred attribute value
+    for this attribute."""
+
 
 class User(Resource[AnyExtension]):
     schemas: Annotated[list[str], Required.true] = [
         "urn:ietf:params:scim:schemas:core:2.0:User"
     ]
 
-    user_name: Annotated[Optional[str], Uniqueness.server, Required.true] = None
+    user_name: Annotated[str | None, Uniqueness.server, Required.true] = None
     """Unique identifier for the User, typically used by the user to directly
     authenticate to the service provider."""
 
-    name: Optional[Name] = None
+    name: Name | None = None
     """The components of the user's real name."""
 
     Name: ClassVar[type[ComplexAttribute]] = Name
 
-    display_name: Optional[str] = None
+    display_name: str | None = None
     """The name of the User, suitable for display to end-users."""
 
-    nick_name: Optional[str] = None
+    nick_name: str | None = None
     """The casual way to address the user in real life, e.g., 'Bob' or 'Bobby'
     instead of 'Robert'."""
 
-    profile_url: Optional[Reference[ExternalReference]] = None
+    profile_url: Reference[ExternalReference] | None = None
     """A fully qualified URL pointing to a page representing the User's online
     profile."""
 
-    title: Optional[str] = None
+    title: str | None = None
     """The user's title, such as "Vice President"."""
 
-    user_type: Optional[str] = None
+    user_type: str | None = None
     """Used to identify the relationship between the organization and the user.
 
     Typical values used might be 'Contractor', 'Employee', 'Intern',
     'Temp', 'External', and 'Unknown', but any value may be used.
     """
 
-    preferred_language: Optional[str] = None
+    preferred_language: str | None = None
     """Indicates the User's preferred written or spoken language.
 
     Generally used for selecting a localized user interface; e.g.,
     'en_US' specifies the language English and country US.
     """
 
-    locale: Optional[str] = None
+    locale: str | None = None
     """Used to indicate the User's default location for purposes of localizing
     items such as currency, date time format, or numerical representations."""
 
-    timezone: Optional[str] = None
+    timezone: str | None = None
     """The User's time zone in the 'Olson' time zone database format, e.g.,
     'America/Los_Angeles'."""
 
-    active: Optional[bool] = None
+    active: bool | None = None
     """A Boolean value indicating the User's administrative status."""
 
-    password: Annotated[Optional[str], Mutability.write_only, Returned.never] = None
+    password: Annotated[str | None, Mutability.write_only, Returned.never] = None
     """The User's cleartext password."""
 
-    emails: Optional[list[Email]] = None
+    emails: list[Email] | None = None
     """Email addresses for the user."""
 
     Emails: ClassVar[type[ComplexAttribute]] = Email
 
-    phone_numbers: Optional[list[PhoneNumber]] = None
+    phone_numbers: list[PhoneNumber] | None = None
     """Phone numbers for the User."""
 
     PhoneNumbers: ClassVar[type[ComplexAttribute]] = PhoneNumber
 
-    ims: Optional[list[Im]] = None
+    ims: list[Im] | None = None
     """Instant messaging addresses for the User."""
 
     Ims: ClassVar[type[ComplexAttribute]] = Im
 
-    photos: Optional[list[Photo]] = None
+    photos: list[Photo] | None = None
     """URLs of photos of the User."""
 
     Photos: ClassVar[type[ComplexAttribute]] = Photo
 
-    addresses: Optional[list[Address]] = None
+    addresses: list[Address] | None = None
     """A physical mailing address for this User."""
 
     Addresses: ClassVar[type[ComplexAttribute]] = Address
 
-    groups: Annotated[Optional[list[GroupMembership]], Mutability.read_only] = None
+    groups: Annotated[list[GroupMembership] | None, Mutability.read_only] = None
     """A list of groups to which the user belongs, either through direct
     membership, through nested groups, or dynamically calculated."""
 
     Groups: ClassVar[type[ComplexAttribute]] = GroupMembership
 
-    entitlements: Optional[list[Entitlement]] = None
+    entitlements: list[Entitlement] | None = None
     """A list of entitlements for the User that represent a thing the User
     has."""
 
     Entitlements: ClassVar[type[ComplexAttribute]] = Entitlement
 
-    roles: Optional[list[Role]] = None
+    roles: list[Role] | None = None
     """A list of roles for the User that collectively represent who the User
     is, e.g., 'Student', 'Faculty'."""
 
     Roles: ClassVar[type[ComplexAttribute]] = Role
 
-    x509_certificates: Optional[list[X509Certificate]] = None
+    x509_certificates: list[X509Certificate] | None = None
     """A list of certificates issued to the User."""
 
     X509Certificates: ClassVar[type[ComplexAttribute]] = X509Certificate

scim2_models/scim_object.py

@@ -3,7 +3,6 @@
 from typing import TYPE_CHECKING
 from typing import Annotated
 from typing import Any
-from typing import Optional
 
 from .annotations import Required
 from .base import BaseModel
@@ -22,7 +21,7 @@ class ScimObject(BaseModel):
 
     def _prepare_model_dump(
         self,
-        scim_ctx: Optional[Context] = Context.DEFAULT,
+        scim_ctx: Context | None = Context.DEFAULT,
         **kwargs: Any,
     ) -> dict[str, Any]:
         kwargs.setdefault("context", {}).setdefault("scim", scim_ctx)
@@ -36,7 +35,7 @@ class ScimObject(BaseModel):
     def model_dump(
         self,
         *args: Any,
-        scim_ctx: Optional[Context] = Context.DEFAULT,
+        scim_ctx: Context | None = Context.DEFAULT,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """Create a model representation that can be included in SCIM messages by using Pydantic :code:`BaseModel.model_dump`.
@@ -53,7 +52,7 @@ class ScimObject(BaseModel):
     def model_dump_json(
         self,
         *args: Any,
-        scim_ctx: Optional[Context] = Context.DEFAULT,
+        scim_ctx: Context | None = Context.DEFAULT,
         **kwargs: Any,
     ) -> str:
         """Create a JSON model representation that can be included in SCIM messages by using Pydantic :code:`BaseModel.model_dump_json`.

scim2_models/urn.py

@@ -1,9 +1,9 @@
 from typing import TYPE_CHECKING
 from typing import Any
-from typing import Optional
 from typing import Union
 
 from .base import BaseModel
+from .utils import _get_path_parts
 from .utils import _normalize_attribute_name
 
 if TYPE_CHECKING:
@@ -23,12 +23,22 @@ def _get_or_create_extension_instance(
     return extension_instance
 
 
-def _normalize_path(model: Optional[type["BaseModel"]], path: str) -> tuple[str, str]:
+def _normalize_path(model: type["BaseModel"] | None, path: str) -> tuple[str, str]:
     """Resolve a path to (schema_urn, attribute_path)."""
     from .resources.resource import Resource
 
     # Absolute URN
     if ":" in path:
+        if (
+            model
+            and issubclass(model, Resource)
+            and (
+                path in model.get_extension_models()
+                or path == model.model_fields["schemas"].default[0]
+            )
+        ):
+            return path, ""
+
         parts = path.rsplit(":", 1)
         return parts[0], parts[1]
 
@@ -42,7 +52,7 @@ def _normalize_path(model: Optional[type["BaseModel"]], path: str) -> tuple[str,
 
 def _validate_model_attribute(model: type["BaseModel"], attribute_base: str) -> None:
     """Validate that an attribute name or a sub-attribute path exist for a given model."""
-    attribute_name, *sub_attribute_blocks = attribute_base.split(".")
+    attribute_name, *sub_attribute_blocks = _get_path_parts(attribute_base)
     sub_attribute_base = ".".join(sub_attribute_blocks)
 
     aliases = {field.validation_alias for field in model.model_fields.values()}
@@ -65,7 +75,7 @@ def _validate_model_attribute(model: type["BaseModel"], attribute_base: str) ->
 
 def _validate_attribute_urn(
     attribute_name: str, resource: type["Resource[Any]"]
-) -> Optional[str]:
+) -> str | None:
     """Validate that an attribute urn is valid or not.
 
     :param attribute_name: The attribute urn to check.
@@ -73,7 +83,7 @@ def _validate_attribute_urn(
     """
     from .resources.resource import Resource
 
-    schema: Optional[Any]
+    schema: Any | None
     schema, attribute_base = _normalize_path(resource, attribute_name)
 
     validated_resource = Resource.get_by_schema([resource], schema)
@@ -90,7 +100,7 @@ def _validate_attribute_urn(
 
 def _resolve_path_to_target(
     resource: "Resource[Any]", path: str
-) -> tuple[Optional[Union["Resource[Any]", "Extension"]], str]:
+) -> tuple[Union["Resource[Any]", "Extension"] | None, str]:
     """Resolve a path to a target and an attribute_path.
 
     The target can be the resource itself, or an extension object.
@@ -100,12 +110,17 @@ def _resolve_path_to_target(
     if not schema_urn:
         return resource, attr_path
 
+    if extension_class := resource.get_extension_model(schema_urn):
+        # Points to the extension root
+        if not attr_path:
+            return resource, extension_class.__name__
+
+        extension_instance = _get_or_create_extension_instance(
+            resource, extension_class
+        )
+        return extension_instance, attr_path
+
     if schema_urn in resource.schemas:
         return resource, attr_path
 
-    extension_class = resource.get_extension_model(schema_urn)
-    if not extension_class:
-        return (None, "")
-
-    extension_instance = _get_or_create_extension_instance(resource, extension_class)
-    return extension_instance, attr_path
+    return (None, "")

scim2_models/utils.py

@@ -3,7 +3,6 @@ import re
 from typing import TYPE_CHECKING
 from typing import Annotated
 from typing import Literal
-from typing import Optional
 from typing import Union
 
 from pydantic import EncodedBytes
@@ -22,8 +21,12 @@ except ImportError:
     # Python 3.9 has no UnionType
     UNION_TYPES = [Union]
 
+_UNDERSCORE_ALPHANUMERIC = re.compile(r"_+([0-9A-Za-z]+)")
+_NON_WORD_UNDERSCORE = re.compile(r"[\W_]+")
+_VALID_PATH_PATTERN = re.compile(r'^[a-zA-Z][a-zA-Z0-9._:\-\[\]"=\s]*$')
 
-def _int_to_str(status: Optional[int]) -> Optional[str]:
+
+def _int_to_str(status: int | None) -> str | None:
     return None if status is None else str(status)
 
 
@@ -87,7 +90,7 @@ def _to_camel(string: str) -> str:
     '$ref' stays '$ref'.
     """
     snake = to_snake(string)
-    camel = re.sub(r"_+([0-9A-Za-z]+)", lambda m: m.group(1).title(), snake)
+    camel = _UNDERSCORE_ALPHANUMERIC.sub(lambda m: m.group(1).title(), snake)
     return camel
 
 
@@ -98,7 +101,7 @@ def _normalize_attribute_name(attribute_name: str) -> str:
     """
     is_extension_attribute = ":" in attribute_name
     if not is_extension_attribute:
-        attribute_name = re.sub(r"[\W_]+", "", attribute_name)
+        attribute_name = _NON_WORD_UNDERSCORE.sub("", attribute_name)
 
     return attribute_name.lower()
 
@@ -122,7 +125,7 @@ def _validate_scim_path_syntax(path: str) -> bool:
 
     # Cannot contain invalid characters (basic check)
     # Allow alphanumeric, dots, underscores, hyphens, colons (for URNs), brackets
-    if not re.match(r'^[a-zA-Z][a-zA-Z0-9._:\-\[\]"=\s]*$', path):
+    if not _VALID_PATH_PATTERN.match(path):
         return False
 
     # If it contains a colon, validate it's a proper URN format
@@ -158,7 +161,7 @@ def _validate_scim_urn_syntax(path: str) -> bool:
     return True
 
 
-def _extract_field_name(path: str) -> Optional[str]:
+def _extract_field_name(path: str) -> str | None:
     """Extract the field name from a path.
 
     For now, only handle simple paths (no filters, no complex expressions).
@@ -181,7 +184,7 @@ def _extract_field_name(path: str) -> Optional[str]:
     return path
 
 
-def _find_field_name(model_class: type["BaseModel"], attr_name: str) -> Optional[str]:
+def _find_field_name(model_class: type["BaseModel"], attr_name: str) -> str | None:
     """Find the actual field name in a resource class from an attribute name.
 
     :param resource_class: The resource class to search in
@@ -195,3 +198,7 @@ def _find_field_name(model_class: type["BaseModel"], attr_name: str) -> Optional
             return field_key
 
     return None
+
+
+def _get_path_parts(path: str) -> list[str]:
+    return path.split(".")