refactor: cleary separate the public and private API

Author: azmeuk

scim2_models/base.py

@@ -23,13 +23,13 @@
 from scim2_models.annotations import Required
 from scim2_models.annotations import Returned
 from scim2_models.context import Context
-from scim2_models.utils import UNION_TYPES
-from scim2_models.utils import find_field_name
-from scim2_models.utils import normalize_attribute_name
-from scim2_models.utils import to_camel
+from scim2_models.utils import _UNION_TYPES
+from scim2_models.utils import _find_field_name
+from scim2_models.utils import _normalize_attribute_name
+from scim2_models.utils import _to_camel
 
 
-def contains_attribute_or_subattributes(
+def _contains_attribute_or_subattributes(
     attribute_urns: list[str], attribute_urn: str
 ) -> bool:
     return attribute_urn in attribute_urns or any(
@@ -43,8 +43,8 @@ class BaseModel(PydanticBaseModel):
 
     model_config = ConfigDict(
         alias_generator=AliasGenerator(
-            validation_alias=normalize_attribute_name,
-            serialization_alias=to_camel,
+            validation_alias=_normalize_attribute_name,
+            serialization_alias=_to_camel,
         ),
         validate_assignment=True,
         populate_by_name=True,
@@ -77,7 +77,7 @@ def get_field_root_type(cls, attribute_name: str) -> Optional[type]:
         attribute_type = cls.model_fields[attribute_name].annotation
 
         # extract 'x' from 'Optional[x]'
-        if get_origin(attribute_type) in UNION_TYPES:
+        if get_origin(attribute_type) in _UNION_TYPES:
             attribute_type = get_args(attribute_type)[0]
 
         # extract 'x' from 'List[x]'
@@ -93,7 +93,7 @@ def get_field_multiplicity(cls, attribute_name: str) -> bool:
         attribute_type = cls.model_fields[attribute_name].annotation
 
         # extract 'x' from 'Optional[x]'
-        if get_origin(attribute_type) in UNION_TYPES:
+        if get_origin(attribute_type) in _UNION_TYPES:
             attribute_type = get_args(attribute_type)[0]
 
         origin = get_origin(attribute_type)
@@ -159,7 +159,7 @@ def normalize_dict_keys(
             result = {}
 
             for key, val in input_dict.items():
-                field_name = find_field_name(model_class, key)
+                field_name = _find_field_name(model_class, key)
                 field_type = (
                     model_class.get_field_root_type(field_name) if field_name else None
                 )
@@ -170,7 +170,7 @@ def normalize_dict_keys(
                 if field_name and field_type == Any:
                     result[key] = normalize_value(val)
                 else:
-                    result[normalize_attribute_name(key)] = normalize_value(
+                    result[_normalize_attribute_name(key)] = normalize_value(
                         val, field_type
                     )
 
@@ -285,11 +285,11 @@ def check_replacement_request_mutability(
             and issubclass(cls, Resource)
             and original is not None
         ):
-            cls.check_mutability_issues(original, obj)
+            cls._check_mutability_issues(original, obj)
         return obj
 
     @classmethod
-    def check_mutability_issues(
+    def _check_mutability_issues(
         cls, original: "BaseModel", replacement: "BaseModel"
     ) -> None:
         """Compare two instances, and check for differences of values on the fields marked as immutable."""
@@ -316,9 +316,9 @@ def check_mutability_issues(
                 original_val = getattr(original, field_name)
                 replacement_value = getattr(replacement, field_name)
                 if original_val is not None and replacement_value is not None:
-                    cls.check_mutability_issues(original_val, replacement_value)
+                    cls._check_mutability_issues(original_val, replacement_value)
 
-    def set_complex_attribute_urns(self) -> None:
+    def _set_complex_attribute_urns(self) -> None:
         """Navigate through attributes and sub-attributes of type ComplexAttribute, and mark them with a '_attribute_urn' attribute.
 
         '_attribute_urn' will later be used by 'get_attribute_urn'.
@@ -359,14 +359,14 @@ def scim_serializer(
         scim_ctx = info.context.get("scim") if info.context else None
 
         if scim_ctx and Context.is_request(scim_ctx):
-            value = self.scim_request_serializer(value, info)
+            value = self._scim_request_serializer(value, info)
 
         if scim_ctx and Context.is_response(scim_ctx):
-            value = self.scim_response_serializer(value, info)
+            value = self._scim_response_serializer(value, info)
 
         return value
 
-    def scim_request_serializer(self, value: Any, info: FieldSerializationInfo) -> Any:
+    def _scim_request_serializer(self, value: Any, info: FieldSerializationInfo) -> Any:
         """Serialize the fields according to mutability indications passed in the serialization context."""
         mutability = self.get_field_annotation(info.field_name, Mutability)
         scim_ctx = info.context.get("scim") if info.context else None
@@ -390,7 +390,9 @@ def scim_request_serializer(self, value: Any, info: FieldSerializationInfo) -> A
 
         return value
 
-    def scim_response_serializer(self, value: Any, info: FieldSerializationInfo) -> Any:
+    def _scim_response_serializer(
+        self, value: Any, info: FieldSerializationInfo
+    ) -> Any:
         """Serialize the fields according to returnability indications passed in the serialization context."""
         returnability = self.get_field_annotation(info.field_name, Returned)
         attribute_urn = self.get_attribute_urn(info.field_name)
@@ -399,17 +401,17 @@ def scim_response_serializer(self, value: Any, info: FieldSerializationInfo) ->
             info.context.get("scim_excluded_attributes", []) if info.context else []
         )
 
-        attribute_urn = normalize_attribute_name(attribute_urn)
-        included_urns = [normalize_attribute_name(urn) for urn in included_urns]
-        excluded_urns = [normalize_attribute_name(urn) for urn in excluded_urns]
+        attribute_urn = _normalize_attribute_name(attribute_urn)
+        included_urns = [_normalize_attribute_name(urn) for urn in included_urns]
+        excluded_urns = [_normalize_attribute_name(urn) for urn in excluded_urns]
 
         if returnability == Returned.never:
             return None
 
         if returnability == Returned.default and (
             (
                 included_urns
-                and not contains_attribute_or_subattributes(
+                and not _contains_attribute_or_subattributes(
                     included_urns, attribute_urn
                 )
             )
@@ -427,7 +429,7 @@ def model_serializer_exclude_none(
         self, handler: SerializerFunctionWrapHandler, info: SerializationInfo
     ) -> dict[str, Any]:
         """Remove `None` values inserted by the :meth:`~scim2_models.base.BaseModel.scim_serializer`."""
-        self.set_complex_attribute_urns()
+        self._set_complex_attribute_urns()
         result = handler(self)
         return {key: value for key, value in result.items() if value is not None}
 

scim2_models/messages/bulk.py

@@ -8,7 +8,7 @@
 
 from ..annotations import Required
 from ..attributes import ComplexAttribute
-from ..utils import int_to_str
+from ..utils import _int_to_str
 from .message import Message
 
 
@@ -42,7 +42,7 @@ class Method(str, Enum):
     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/messages/error.py

@@ -4,7 +4,7 @@
 from pydantic import PlainSerializer
 
 from ..annotations import Required
-from ..utils import int_to_str
+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."""
 

scim2_models/messages/list_response.py

@@ -13,11 +13,11 @@
 from ..annotations import Required
 from ..context import Context
 from ..resources.resource import AnyResource
-from .message import GenericMessageMetaclass
 from .message import Message
+from .message import _GenericMessageMetaclass
 
 
-class ListResponse(Message, Generic[AnyResource], metaclass=GenericMessageMetaclass):
+class ListResponse(Message, Generic[AnyResource], metaclass=_GenericMessageMetaclass):
     schemas: Annotated[list[str], Required.true] = [
         "urn:ietf:params:scim:api:messages:2.0:ListResponse"
     ]

scim2_models/messages/message.py

@@ -14,14 +14,14 @@
 
 from ..base import BaseModel
 from ..scim_object import ScimObject
-from ..utils import UNION_TYPES
+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(
+def _create_schema_discriminator(
     resource_types_schemas: list[str],
 ) -> Callable[[Any], Optional[str]]:
     """Create a schema discriminator function for the given resource schemas.
@@ -51,7 +51,7 @@ def get_schema_from_payload(payload: Any) -> Optional[str]:
     return get_schema_from_payload
 
 
-def get_tag(resource_type: type[BaseModel]) -> Tag:
+def _get_tag(resource_type: type[BaseModel]) -> Tag:
     """Create Pydantic tag from resource type schema.
 
     :param resource_type: SCIM resource type
@@ -60,7 +60,7 @@ def get_tag(resource_type: type[BaseModel]) -> Tag:
     return Tag(resource_type.model_fields["schemas"].default[0])
 
 
-def create_tagged_resource_union(resource_union: Any) -> Any:
+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
@@ -69,7 +69,7 @@ def create_tagged_resource_union(resource_union: Any) -> Any:
     :param resource_union: Union type of SCIM resources
     :return: Annotated discriminated union or original type
     """
-    if get_origin(resource_union) not in UNION_TYPES:
+    if get_origin(resource_union) not in _UNION_TYPES:
         return resource_union
 
     resource_types = get_args(resource_union)
@@ -81,19 +81,19 @@ def create_tagged_resource_union(resource_union: Any) -> Any:
     ]
 
     # Create discriminator function with schemas captured in closure
-    schema_discriminator = create_schema_discriminator(resource_types_schemas)
+    schema_discriminator = _create_schema_discriminator(resource_types_schemas)
     discriminator = Discriminator(schema_discriminator)
 
     tagged_resources = [
-        Annotated[resource_type, get_tag(resource_type)]
+        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):
+class _GenericMessageMetaclass(ModelMetaclass):
     """Metaclass for SCIM generic types with discriminated unions."""
 
     def __new__(
@@ -103,7 +103,7 @@ def __new__(
         if kwargs.get("__pydantic_generic_metadata__") and kwargs[
             "__pydantic_generic_metadata__"
         ].get("args"):
-            tagged_union = create_tagged_resource_union(
+            tagged_union = _create_tagged_resource_union(
                 kwargs["__pydantic_generic_metadata__"]["args"][0]
             )
             kwargs["__pydantic_generic_metadata__"]["args"] = (tagged_union,)
@@ -112,7 +112,7 @@ def __new__(
         return klass
 
 
-def get_resource_class(obj) -> Optional[type[Resource]]:
+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]