Feature/devexp 1482 python manage additional properties as passthrough (#3)

* feat(core) add legacy_extra_fields_normalization boolean

* feat(core): implement legacy extra fields normalization as a passthrough mechanism

Author: marcos-sinch

CHANGELOG.md

@@ -18,6 +18,14 @@ All notable changes to the **Sinch Python SDK** are documented in this file.
 
 ## v2.2.0 – unreleased
 
+### SDK
+
+- **[design]** Extra fields on request and response models now pass through unchanged by default (no camelCase/snake_case rewriting). A new `Configuration(legacy_extra_fields_normalization=True)` flag restores the previous auto-conversion behavior for callers who depend on it; the flag is transitional and will be removed in 3.0.
+
+### Numbers
+
+- **[refactor]** `voice_configuration`, `sms_configuration`, and `number_pattern` request fields are now typed Pydantic models instead of raw dicts with validators. Added `VoiceConfigurationCustom`/`ScheduledVoiceProvisioningCustom` response variants for unrecognized voice configuration types.
+
 ### Conversation
 
 - **[feature]** Conversation Apps API: `create`, `get`, `list`, `update`, and `delete` operations, with full model, endpoints and unit/e2e test coverage.

sinch/core/clients/sinch_client_configuration.py

@@ -1,4 +1,5 @@
 import logging
+import warnings
 from logging import Logger
 
 from sinch.core.ports.http_transport import HTTPTransport
@@ -8,6 +9,16 @@
 class Configuration:
     """
     Sinch client configuration object.
+
+    :param legacy_extra_fields_normalization: When
+        ``True``, restores the behavior before 2.2.0 where extra fields on request/response models were
+        auto-converted to the api convention ``snake_case`` or ``camelCase``. When
+        ``False`` (default), extra fields pass through unchanged in both
+        directions.
+
+        .. deprecated:: 2.2
+            This flag is transitional and will be removed in 3.0, along with
+            the legacy auto-conversion behavior it restores.
     """
     def __init__(
         self,
@@ -23,14 +34,16 @@ def __init__(
         sms_api_token: str = None,
         sms_region: str = None,
         conversation_region: str = None,
+        legacy_extra_fields_normalization: bool = False,
     ):
         self.key_id = key_id
         self.key_secret = key_secret
         self.project_id = project_id
         self.connection_timeout = connection_timeout
         self.sms_api_token = sms_api_token
         self.service_plan_id = service_plan_id
-        
+        self.legacy_extra_fields_normalization = legacy_extra_fields_normalization
+
         # Determine authentication method based on provided parameters
         self._authentication_method = self._determine_authentication_method()
         self.auth_origin = "https://auth.sinch.com"

sinch/core/clients/sinch_client_sync.py

@@ -14,6 +14,16 @@ class SinchClient:
     Synchronous implementation of the Sinch Client
     By default this implementation uses HTTPTransportRequests based on Requests library
     Custom Sync HTTPTransport implementation can be provided via `transport` argument
+
+    :param legacy_extra_fields_normalization: When
+        ``True``, restores the behavior before 2.2.0 where extra fields on request/response models were
+        auto-converted to the api convention ``snake_case`` or ``camelCase``. When
+        ``False`` (default), extra fields pass through unchanged in both
+        directions.
+
+        .. deprecated:: 2.2
+            This flag is transitional and will be removed in 3.0, along with
+            the legacy auto-conversion behavior it restores.
     """
     def __init__(
         self,
@@ -26,6 +36,7 @@ def __init__(
         sms_api_token: str = None,
         sms_region: str = None,
         conversation_region: str = None,
+        legacy_extra_fields_normalization: bool = False,
     ):
         self.configuration = Configuration(
             key_id=key_id,
@@ -39,6 +50,7 @@ def __init__(
             sms_api_token=sms_api_token,
             sms_region=sms_region,
             conversation_region=conversation_region,
+            legacy_extra_fields_normalization=legacy_extra_fields_normalization,
         )
 
         self.authentication = Authentication(self)

sinch/core/models/internal/base_model_config.py

@@ -1,9 +1,45 @@
 import re
-from typing import Any
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any, Generator
 
 from pydantic import BaseModel, ConfigDict, SerializationInfo, model_serializer
 from pydantic.functional_serializers import SerializerFunctionWrapHandler
 
+# Request-scoped normalization policy for extra fields.
+#
+# Default (False) is passthrough: extra fields are sent/exposed exactly as
+# given by the caller/server. Setting this to True for the duration of a
+# scope restores the legacy auto-conversion (camelCase on the wire,
+# snake_case on Python attributes) that this SDK used before passthrough
+# became the default.
+#
+# This is deliberately a transitional mechanism: `legacy_extra_fields_normalization`
+# is expected to be removed in 3.0, once passthrough is the only behavior.
+# Keeping it confined to a ContextVar plus the two hooks below.
+#
+# The scope is opened once per request, around `HTTPTransport.request()`,
+# which is the one place that knows which client's `Configuration` a given
+# call belongs to.
+_legacy_extra_fields_normalization: ContextVar[bool] = ContextVar(
+    "legacy_extra_fields_normalization", default=False
+)
+
+
+@contextmanager
+def legacy_extra_fields_normalization_scope(enabled: bool) -> Generator[None, None, None]:
+    """Scope the extra-field normalization policy for the duration of the block.
+
+    :param enabled: When True, extra fields are auto-converted matching the
+        legacy behavior. When False, extra fields pass
+        through untouched in both directions.
+    """
+    token = _legacy_extra_fields_normalization.set(enabled)
+    try:
+        yield
+    finally:
+        _legacy_extra_fields_normalization.reset(token)
+
 
 def _to_camel_case(snake_str: str) -> str:
     """Convert ``snake_case`` to ``camelCase`` preserving consecutive underscores.
@@ -44,25 +80,62 @@ def _camelize_keys(value: Any) -> Any:
 
 
 class _SnakifyExtrasOnInit:
-    """Normalize ``__pydantic_extra__`` keys to ``snake_case`` at validation time."""
+    """Normalize extra keys to ``snake_case``, at validation time and at dump time.
+
+    Only applies when the legacy scope (:func:`legacy_extra_fields_normalization_scope`)
+    is active; otherwise extra keys pass through exactly as given.
+
+    Two hooks are needed because it is used as a base for both
+    response and request models:
+
+    - As a response base, extras are normalized in ``model_post_init``
+      (construction time), so that attribute access (``response.extra_field``)
+      reflects the policy.
+    - As a request base, the
+      model is constructed earlier, in the public API method, before that
+      scope starts, so ``model_post_init`` alone would always see the
+      ambient default. The ``model_serializer`` below re-checks the policy
+      at dump time instead, when it's invoked from ``request_body()``
+    """
 
     def model_post_init(self, __context: Any) -> None:
+        if not _legacy_extra_fields_normalization.get():
+            return
         extra = self.__pydantic_extra__
         if extra:
             self.__pydantic_extra__ = {_to_snake_case(k): v for k, v in extra.items()}
 
+    @model_serializer(mode="wrap")
+    def _serialize_with_snake_extras(
+        self, handler: SerializerFunctionWrapHandler, info: SerializationInfo
+    ) -> dict:
+        data = handler(self)
+        if not _legacy_extra_fields_normalization.get():
+            return data
+
+        extra_keys = set(getattr(self, "__pydantic_extra__", None) or {})
+        if not extra_keys:
+            return data
+        return {
+            (_to_snake_case(k) if k in extra_keys else k): v
+            for k, v in data.items()
+        }
+
 
 class _CamelizeKeysOnDump:
     """Recursively rewrite every dict key in the serialized output to
     ``camelCase`` when ``by_alias=True``.
+
+    Only applies when the legacy scope (:func:`legacy_extra_fields_normalization_scope`)
+    is active; otherwise the serialized output passes through unchanged.
     """
 
     @model_serializer(mode="wrap")
     def _serialize_with_camel_extras(
         self, handler: SerializerFunctionWrapHandler, info: SerializationInfo
     ) -> dict:
         data = handler(self)
-        if info.by_alias:
+        if info.by_alias and _legacy_extra_fields_normalization.get():
             data = _camelize_keys(data)
         return data
 

sinch/core/ports/http_transport.py

@@ -11,6 +11,7 @@
 from sinch.core.endpoint import HTTPEndpoint
 from sinch.core.models.http_request import HttpRequest
 from sinch.core.models.http_response import HTTPResponse
+from sinch.core.models.internal.base_model_config import legacy_extra_fields_normalization_scope
 from sinch.core.exceptions import ValidationException, SinchException
 from sinch.core.enums import HTTPAuthentication
 from sinch import __version__ as sdk_version
@@ -96,21 +97,24 @@ def request(self, endpoint: HTTPEndpoint) -> HTTPResponse:
         :returns: The handled HTTP response.
         :rtype: HTTPResponse
         """
-        if self._legacy_send:
-            return self._legacy_request(endpoint)
-
-        request_data = self.prepare_request(endpoint)
-        request_data = self.authenticate(endpoint, request_data)
+        with legacy_extra_fields_normalization_scope(
+            self.sinch.configuration.legacy_extra_fields_normalization
+        ):
+            if self._legacy_send:
+                return self._legacy_request(endpoint)
 
-        http_response = self._send_with_retries(endpoint, request_data)
+            request_data = self.prepare_request(endpoint)
+            request_data = self.authenticate(endpoint, request_data)
 
-        if self._should_refresh_token(endpoint, http_response):
-            used_token = self._get_bearer_token_from_request(request_data)
-            new_token = self.sinch.configuration.token_manager.refresh_auth_token(used_token)
-            self._set_bearer_token(request_data, new_token.access_token)
             http_response = self._send_with_retries(endpoint, request_data)
 
-        return endpoint.handle_response(http_response)
+            if self._should_refresh_token(endpoint, http_response):
+                used_token = self._get_bearer_token_from_request(request_data)
+                new_token = self.sinch.configuration.token_manager.refresh_auth_token(used_token)
+                self._set_bearer_token(request_data, new_token.access_token)
+                http_response = self._send_with_retries(endpoint, request_data)
+
+            return endpoint.handle_response(http_response)
 
 
     def _send_with_retries(

sinch/domains/numbers/models/v1/internal/__init__.py

@@ -39,6 +39,7 @@
     VoiceConfigurationEST,
     VoiceConfigurationFAX,
     VoiceConfigurationRTC,
+    VoiceConfigurationRequestUnion,
 )
 
 __all__ = [
@@ -58,4 +59,5 @@
     "VoiceConfigurationEST",
     "VoiceConfigurationFAX",
     "VoiceConfigurationRTC",
+    "VoiceConfigurationRequestUnion",
 ]

sinch/domains/numbers/models/v1/internal/rent_any_number_request.py

@@ -1,10 +1,13 @@
-from typing import Optional, Dict, Any
+from typing import Optional
 from pydantic import Field, StrictStr, conlist
 from sinch.domains.numbers.models.v1.types import CapabilityType, NumberType
-from sinch.domains.numbers.models.v1.utils.validators import (
-    validate_sms_voice_configuration,
-    validate_number_pattern,
+from sinch.domains.numbers.models.v1.internal.sms_configuration_request import (
+    SmsConfigurationRequest,
 )
+from sinch.domains.numbers.models.v1.internal.voice_configuration_request import (
+    VoiceConfigurationRequestUnion,
+)
+from sinch.domains.numbers.models.v1.shared.number_pattern import NumberPattern
 from sinch.domains.numbers.models.v1.internal.base import (
     BaseModelConfigurationRequest,
 )
@@ -16,24 +19,16 @@ class RentAnyNumberRequest(BaseModelConfigurationRequest):
         description="ISO 3166-1 alpha-2 country code. Example: US, GB or SE.",
     )
     number_type: NumberType = Field(alias="type")
-    number_pattern: Optional[Dict[str, Any]] = Field(
+    number_pattern: Optional[NumberPattern] = Field(
         default=None, alias="numberPattern"
     )
     capabilities: Optional[conlist(CapabilityType)] = Field(default=None)
-    sms_configuration: Optional[Dict[str, Any]] = Field(
+    sms_configuration: Optional[SmsConfigurationRequest] = Field(
         default=None, alias="smsConfiguration"
     )
-    voice_configuration: Optional[Dict[str, Any]] = Field(
+    voice_configuration: Optional[VoiceConfigurationRequestUnion] = Field(
         default=None, alias="voiceConfiguration"
     )
     event_destination_target: Optional[StrictStr] = Field(
         default=None, alias="callbackUrl"
     )
-
-    def __init__(self, **data):
-        """
-        Custom initializer to validate nested dictionaries.
-        """
-        validate_sms_voice_configuration(data)
-        validate_number_pattern(data)
-        super().__init__(**data)

sinch/domains/numbers/models/v1/internal/rent_number_request.py

@@ -1,7 +1,10 @@
-from typing import Optional, Dict
+from typing import Optional
 from pydantic import Field, StrictStr
-from sinch.domains.numbers.models.v1.utils.validators import (
-    validate_sms_voice_configuration,
+from sinch.domains.numbers.models.v1.internal.sms_configuration_request import (
+    SmsConfigurationRequest,
+)
+from sinch.domains.numbers.models.v1.internal.voice_configuration_request import (
+    VoiceConfigurationRequestUnion,
 )
 from sinch.domains.numbers.models.v1.internal.base import (
     BaseModelConfigurationRequest,
@@ -13,20 +16,12 @@ class RentNumberRequest(BaseModelConfigurationRequest):
         alias="phoneNumber",
         description="Phone number in E.164 format with leading '+'. Example: '+12025550134'.",
     )
-    # Accepts only dictionary input, not Pydantic models
-    sms_configuration: Optional[Dict] = Field(
+    sms_configuration: Optional[SmsConfigurationRequest] = Field(
         default=None, alias="smsConfiguration"
     )
-    voice_configuration: Optional[Dict] = Field(
+    voice_configuration: Optional[VoiceConfigurationRequestUnion] = Field(
         default=None, alias="voiceConfiguration"
     )
     event_destination_target: Optional[StrictStr] = Field(
         default=None, alias="callbackUrl"
     )
-
-    def __init__(self, **data):
-        """
-        Custom initializer to validate nested dictionaries.
-        """
-        validate_sms_voice_configuration(data)
-        super().__init__(**data)

sinch/domains/numbers/models/v1/internal/update_number_configuration_request.py

@@ -1,10 +1,13 @@
-from typing import Optional, Dict
+from typing import Optional
 from pydantic import Field, StrictStr
 from sinch.domains.numbers.models.v1.internal.base import (
     BaseModelConfigurationRequest,
 )
-from sinch.domains.numbers.models.v1.utils.validators import (
-    validate_sms_voice_configuration,
+from sinch.domains.numbers.models.v1.internal.sms_configuration_request import (
+    SmsConfigurationRequest,
+)
+from sinch.domains.numbers.models.v1.internal.voice_configuration_request import (
+    VoiceConfigurationRequestUnion,
 )
 
 
@@ -16,20 +19,12 @@ class UpdateNumberConfigurationRequest(BaseModelConfigurationRequest):
     display_name: Optional[StrictStr] = Field(
         default=None, alias="displayName"
     )
-    sms_configuration: Optional[Dict] = Field(
+    sms_configuration: Optional[SmsConfigurationRequest] = Field(
         default=None, alias="smsConfiguration"
     )
-    voice_configuration: Optional[Dict] = Field(
+    voice_configuration: Optional[VoiceConfigurationRequestUnion] = Field(
         default=None, alias="voiceConfiguration"
     )
     event_destination_target: Optional[StrictStr] = Field(
         default=None, alias="callbackUrl"
     )
-
-    def __init__(self, **data):
-        """
-        Custom initializer to validate nested dictionaries.
-        """
-        if data.get("sms_configuration") or data.get("voice_configuration"):
-            validate_sms_voice_configuration(data)
-        super().__init__(**data)