fix: allow non canonical values for Enums

Author: azmeuk

doc/changelog.rst

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+[0.4.3] - Unreleased
+--------------------
+
+Fixed
+^^^^^
+- Allow non canonical values for enums. :issue:`34`
+
 [0.4.2] - 2025-08-05
 --------------------
 

scim2_models/attributes.py

@@ -1,9 +1,15 @@
+from enum import Enum
 from inspect import isclass
 from typing import Annotated
 from typing import Any
 from typing import Optional
 from typing import get_origin
 
+try:
+    from typing import Self
+except ImportError:
+    from typing_extensions import Self
+
 from pydantic import Field
 
 from .annotations import Mutability
@@ -13,6 +19,35 @@
 from .reference import Reference
 
 
+class ExtensibleStringEnum(str, Enum):
+    """String enum that accepts arbitrary values while preserving canonical ones.
+
+    This enum allows both predefined canonical values and arbitrary string values,
+    conforming to :rfc:`RFC 7643 <7643>` which permits service providers to accept
+    additional type values beyond the recommended set.
+    """
+
+    def __str__(self) -> str:
+        """Return just the string value, not the enum representation."""
+        return str(self.value)
+
+    @classmethod
+    def _missing_(cls, value: Any) -> Self:
+        """Handle unknown enum values by creating dynamic instances.
+
+        :param value: The value to create an enum instance for
+        :return: A new enum instance for the given value
+        :raises ValueError: If value is not a string
+        """
+        if isinstance(value, str):
+            # Create a pseudo enum member for unknown string values
+            obj = str.__new__(cls, value)
+            obj._name_ = value
+            obj._value_ = value
+            return obj
+        raise ValueError(f"{value} is not a valid string value for {cls.__name__}")
+
+
 class ComplexAttribute(BaseModel):
     """A complex attribute as defined in :rfc:`RFC7643 §2.3.8 <7643#section-2.3.8>`."""
 

scim2_models/resources/user.py

@@ -1,4 +1,3 @@
-from enum import Enum
 from typing import Annotated
 from typing import ClassVar
 from typing import Literal
@@ -14,6 +13,7 @@
 from ..annotations import Returned
 from ..annotations import Uniqueness
 from ..attributes import ComplexAttribute
+from ..attributes import ExtensibleStringEnum
 from ..attributes import MultiValuedComplexAttribute
 from ..reference import ExternalReference
 from ..reference import Reference
@@ -49,7 +49,7 @@ class Name(ComplexAttribute):
 
 
 class Email(MultiValuedComplexAttribute):
-    class Type(str, Enum):
+    class Type(ExtensibleStringEnum):
         work = "work"
         home = "home"
         other = "other"
@@ -70,7 +70,7 @@ class Type(str, Enum):
 
 
 class PhoneNumber(MultiValuedComplexAttribute):
-    class Type(str, Enum):
+    class Type(ExtensibleStringEnum):
         work = "work"
         home = "home"
         mobile = "mobile"
@@ -97,7 +97,7 @@ class Type(str, Enum):
 
 
 class Im(MultiValuedComplexAttribute):
-    class Type(str, Enum):
+    class Type(ExtensibleStringEnum):
         aim = "aim"
         gtalk = "gtalk"
         icq = "icq"
@@ -125,7 +125,7 @@ class Type(str, Enum):
 
 
 class Photo(MultiValuedComplexAttribute):
-    class Type(str, Enum):
+    class Type(ExtensibleStringEnum):
         photo = "photo"
         thumbnail = "thumbnail"
 
@@ -145,7 +145,7 @@ class Type(str, Enum):
 
 
 class Address(MultiValuedComplexAttribute):
-    class Type(str, Enum):
+    class Type(ExtensibleStringEnum):
         work = "work"
         home = "home"
         other = "other"

tests/test_user.py

@@ -1,12 +1,15 @@
 import datetime
 
+import pytest
+
 from scim2_models import Address
 from scim2_models import Email
 from scim2_models import Im
 from scim2_models import PhoneNumber
 from scim2_models import Photo
 from scim2_models import Reference
 from scim2_models import User
+from scim2_models.attributes import ExtensibleStringEnum
 
 
 def test_minimal_user(load_sample):
@@ -124,3 +127,171 @@ def test_full_user(load_sample):
         obj.meta.location
         == "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646"
     )
+
+
+class TestExtensibleStringEnum:
+    """Test the base ExtensibleStringEnum behavior."""
+
+    def test_canonical_values(self):
+        """Test that canonical enum values work as expected."""
+
+        class TestEnum(ExtensibleStringEnum):
+            foo = "foo"
+            bar = "bar"
+
+        assert TestEnum.foo == "foo"
+        assert TestEnum.bar == "bar"
+        assert str(TestEnum.foo) == "foo"
+
+    def test_arbitrary_values(self):
+        """Test that arbitrary string values are accepted."""
+
+        class TestEnum(ExtensibleStringEnum):
+            foo = "foo"
+            bar = "bar"
+
+        # Create instances with arbitrary values
+        custom = TestEnum("custom_value")
+        another = TestEnum("another_value")
+
+        assert str(custom) == "custom_value"
+        assert str(another) == "another_value"
+        assert custom == "custom_value"
+        assert another == "another_value"
+
+    def test_non_string_values_rejected(self):
+        """Test that non-string values are rejected."""
+
+        class TestEnum(ExtensibleStringEnum):
+            foo = "foo"
+
+        with pytest.raises(ValueError, match="is not a valid string value"):
+            TestEnum(123)
+
+        with pytest.raises(ValueError, match="is not a valid string value"):
+            TestEnum(None)
+
+
+class TestComplexAttributeExtensibleTypes:
+    """Test that complex attribute Type classes accept arbitrary values per RFC 7643."""
+
+    def test_email_canonical_and_arbitrary_types(self):
+        """Test Email with both canonical and arbitrary type values."""
+        # Canonical types
+        email = Email(value="[email protected]", type=Email.Type.work)
+        assert email.type == Email.Type.work
+        assert str(email.type) == "work"
+
+        email = Email(value="[email protected]", type=Email.Type.home)
+        assert email.type == Email.Type.home
+        assert str(email.type) == "home"
+
+        # Arbitrary types per RFC 7643
+        email = Email(value="[email protected]", type="custom_type")
+        assert str(email.type) == "custom_type"
+
+        email = Email(value="[email protected]", type="business")
+        assert str(email.type) == "business"
+
+    def test_phone_canonical_and_arbitrary_types(self):
+        """Test PhoneNumber with both canonical and arbitrary type values."""
+        # Canonical types
+        phone = PhoneNumber(value="+1234567890", type=PhoneNumber.Type.mobile)
+        assert phone.type == PhoneNumber.Type.mobile
+        assert str(phone.type) == "mobile"
+
+        # Arbitrary types per RFC 7643
+        phone = PhoneNumber(value="+1234567890", type="voip")
+        assert str(phone.type) == "voip"
+
+        phone = PhoneNumber(value="+1234567890", type="satellite")
+        assert str(phone.type) == "satellite"
+
+    def test_address_canonical_and_arbitrary_types(self):
+        """Test Address with both canonical and arbitrary type values."""
+        # Canonical types
+        addr = Address(formatted="123 Main St", type=Address.Type.home)
+        assert addr.type == Address.Type.home
+        assert str(addr.type) == "home"
+
+        # Arbitrary types per RFC 7643
+        addr = Address(formatted="123 Main St", type="vacation")
+        assert str(addr.type) == "vacation"
+
+        addr = Address(formatted="123 Main St", type="shipping")
+        assert str(addr.type) == "shipping"
+
+    def test_im_canonical_and_arbitrary_types(self):
+        """Test Im with both canonical and arbitrary type values."""
+        # Canonical types
+        im = Im(value="[email protected]", type=Im.Type.skype)
+        assert im.type == Im.Type.skype
+        assert str(im.type) == "skype"
+
+        # Arbitrary types per RFC 7643
+        im = Im(value="[email protected]", type="discord")
+        assert str(im.type) == "discord"
+
+        im = Im(value="[email protected]", type="teams")
+        assert str(im.type) == "teams"
+
+    def test_photo_canonical_and_arbitrary_types(self):
+        """Test Photo with both canonical and arbitrary type values."""
+        # Canonical types
+        photo = Photo(value="http://example.com/photo.jpg", type=Photo.Type.photo)
+        assert photo.type == Photo.Type.photo
+        assert str(photo.type) == "photo"
+
+        # Arbitrary types per RFC 7643
+        photo = Photo(value="http://example.com/avatar.jpg", type="avatar")
+        assert str(photo.type) == "avatar"
+
+        photo = Photo(value="http://example.com/profile.jpg", type="profile")
+        assert str(photo.type) == "profile"
+
+    def test_type_serialization_compatibility(self):
+        """Test that serialization works with both canonical and arbitrary values."""
+        # Canonical type
+        email_canonical = Email(value="[email protected]", type=Email.Type.work)
+        data = email_canonical.model_dump()
+        assert data["type"] == "work"
+
+        # Arbitrary type
+        email_custom = Email(value="[email protected]", type="custom_business")
+        data = email_custom.model_dump()
+        assert data["type"] == "custom_business"
+
+    def test_round_trip_serialization(self):
+        """Test that arbitrary values can be serialized and deserialized correctly."""
+        # Test with arbitrary type
+        original = Email(value="[email protected]", type="custom_type")
+        data = original.model_dump()
+        restored = Email.model_validate(data)
+
+        assert str(restored.type) == "custom_type"
+        assert restored.type == "custom_type"
+        assert restored.value == "[email protected]"
+
+    def test_rfc_7643_compliance(self):
+        """Test compliance with RFC 7643 extensibility requirements.
+
+        RFC 7643 states that service providers MAY allow additional type values
+        beyond the canonical ones like "work", "home", and "other".
+        """
+        # Should accept canonical values
+        email = Email(value="[email protected]", type="work")
+        assert str(email.type) == "work"
+
+        phone = PhoneNumber(value="+1234567890", type="mobile")
+        assert str(phone.type) == "mobile"
+
+        # Should accept additional values as specified in RFC
+        email = Email(value="[email protected]", type="emergency")
+        assert str(email.type) == "emergency"
+
+        phone = PhoneNumber(value="+1234567890", type="voip")
+        assert str(phone.type) == "voip"
+
+        # Test GitHub issue #34 specific case
+        email_company = Email(value="[email protected]", type="company")
+        assert str(email_company.type) == "company"