fix: restore deprecation shims and move type_encoders to serialization plugin

Two corrections to the serializer refactor on this branch:

1. Restore advanced_alchemy/_serialization.py and
   advanced_alchemy/service/typing.py as deprecation shims. Both modules
   are released in v1.9.x with substantial public surface (BaseModel,
   schema_dump, type guards, encode/decode_json, the *_INSTALLED flags,
   etc.) so deleting them outright is a breaking change. The shims re-
   export every name from its new home (advanced_alchemy.utils.serialization,
   advanced_alchemy.utils.serializers, advanced_alchemy.typing) and emit a
   DeprecationWarning via the project's warn_deprecation helper, scheduled
   for removal in 2.0.

2. Move the Litestar type_encoders / type_decoders wiring from
   SQLAlchemyInitPlugin.on_app_init to SQLAlchemySerializationPlugin —
   serialization registration is a serialization-plugin concern. The
   serialization plugin now implements both SerializationPlugin and
   InitPluginProtocol so AA's built-in encoders are still picked up
   transparently when SQLAlchemyPlugin is used.

Add tests covering: every shim name resolves to the canonical object and
emits a DeprecationWarning; PYDANTIC_USE_FAILFAST is preserved without a
warning; the init plugin no longer touches type_encoders; the
serialization plugin merges AA encoders/decoders with user precedence;
and the serialization plugin satisfies both Litestar protocols.

Author: cofin

advanced_alchemy/_serialization.py

@@ -0,0 +1,57 @@
+# pyright: reportUnsupportedDunderAll=false
+"""Deprecated shim for ``advanced_alchemy._serialization``.
+
+Re-exports the public surface that lived here in v1.x from its new
+locations under :mod:`advanced_alchemy.utils.serialization` and
+:mod:`advanced_alchemy.typing`.  Importing any name from this module
+emits a :class:`DeprecationWarning` via the project's
+:func:`~advanced_alchemy.utils.deprecation.warn_deprecation` helper.
+
+This module will be removed in 2.0.
+"""
+
+from typing import Any
+
+from advanced_alchemy.utils.deprecation import warn_deprecation
+
+_RENAMES: "dict[str, tuple[str, str]]" = {
+    "BaseModel": ("advanced_alchemy.typing", "BaseModel"),
+    "PYDANTIC_INSTALLED": ("advanced_alchemy.typing", "PYDANTIC_INSTALLED"),
+    "encode_json": ("advanced_alchemy.utils.serialization", "encode_json"),
+    "decode_json": ("advanced_alchemy.utils.serialization", "decode_json"),
+    "encode_complex_type": ("advanced_alchemy.utils.serialization", "encode_complex_type"),
+    "decode_complex_type": ("advanced_alchemy.utils.serialization", "decode_complex_type"),
+    "convert_datetime_to_gmt_iso": ("advanced_alchemy.utils.serialization", "convert_datetime_to_gmt_iso"),
+    "convert_date_to_iso": ("advanced_alchemy.utils.serialization", "convert_date_to_iso"),
+}
+
+# Names below are resolved lazily via ``__getattr__`` for the deprecation
+# warning. ruff's F822 / pyright's reportUnsupportedDunderAll don't see them
+# at module level — that's the point.
+__all__ = (  # noqa: F822
+    "PYDANTIC_INSTALLED",
+    "BaseModel",
+    "convert_date_to_iso",
+    "convert_datetime_to_gmt_iso",
+    "decode_complex_type",
+    "decode_json",
+    "encode_complex_type",
+    "encode_json",
+)
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _RENAMES:
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)
+    new_module, new_name = _RENAMES[name]
+    warn_deprecation(
+        version="1.10.0",
+        removal_in="2.0.0",
+        deprecated_name=f"{__name__}.{name}",
+        kind="import",
+        alternative=f"{new_module}.{new_name}",
+    )
+    import importlib
+
+    return getattr(importlib.import_module(new_module), new_name)

advanced_alchemy/extensions/litestar/plugins/init/plugin.py

@@ -34,11 +34,8 @@
     StatementTypeT,
 )
 from advanced_alchemy.service import ModelDictListT, ModelDictT, ModelDTOT, ModelOrRowMappingT, ModelT, OffsetPagination
-from advanced_alchemy.utils.serialization import DEFAULT_TYPE_ENCODERS
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
-
     from click import Group
     from litestar.config.app import AppConfig
     from litestar.types import BeforeMessageSendHookHandler
@@ -48,55 +45,6 @@
 __all__ = ("SQLAlchemyInitPlugin",)
 
 
-def _get_aa_type_encoders() -> dict[type, "Callable[[Any], Any]"]:
-    """Get Advanced Alchemy's built-in type encoders.
-
-    These encoders handle database-specific types that need special
-    serialization. They are added to Litestar's type_encoders with
-    lower precedence than user-defined encoders.
-
-    Returns:
-        Dictionary of type to encoder function mappings.
-    """
-    encoders: dict[type, Callable[[Any], Any]] = {**DEFAULT_TYPE_ENCODERS}
-
-    # asyncpg UUID type (PostgreSQL asyncpg driver)
-    with contextlib.suppress(ImportError):
-        from asyncpg.pgproto import pgproto  # pyright: ignore[reportMissingImports]
-
-        encoders[pgproto.UUID] = str
-
-    # uuid_utils UUID type (fast UUID implementation)
-    with contextlib.suppress(ImportError):
-        import uuid_utils  # pyright: ignore[reportMissingImports]
-
-        encoders[uuid_utils.UUID] = str  # pyright: ignore[reportUnknownMemberType]
-
-    return encoders
-
-
-def _get_aa_type_decoders() -> list[tuple["Callable[[Any], bool]", "Callable[[type, Any], Any]"]]:
-    """Get Advanced Alchemy's built-in type decoders.
-
-    These decoders handle database-specific types that need special
-    deserialization during request parsing.
-
-    Returns:
-        List of (predicate, decoder) tuples for Litestar's type_decoders.
-    """
-    decoders: list[tuple[Callable[[Any], bool], Callable[[type, Any], Any]]] = []
-
-    # uuid_utils UUID type decoder
-    with contextlib.suppress(ImportError):
-        import uuid_utils  # pyright: ignore[reportMissingImports]
-
-        decoders.append(
-            (lambda x: x is uuid_utils.UUID, lambda t, v: t(str(v)))  # pyright: ignore[reportUnknownMemberType]
-        )
-
-    return decoders
-
-
 signature_namespace_values: dict[str, Any] = {
     "BeforeAfter": BeforeAfter,
     "OnBeforeAfter": OnBeforeAfter,
@@ -179,15 +127,6 @@ def on_app_init(self, app_config: "AppConfig") -> "AppConfig":
         """
         self._validate_config()
 
-        # Add AA built-in type encoders/decoders
-        # These are added BEFORE user encoders so user config takes precedence
-        aa_encoders = _get_aa_type_encoders()
-        aa_decoders = _get_aa_type_decoders()
-
-        # Merge: AA built-ins first, then user encoders override
-        app_config.type_encoders = {**aa_encoders, **(app_config.type_encoders or {})}
-        app_config.type_decoders = [*aa_decoders, *(app_config.type_decoders or [])]
-
         with contextlib.suppress(ImportError):
             from asyncpg.pgproto import pgproto  # pyright: ignore[reportMissingImports]
 

advanced_alchemy/extensions/litestar/plugins/serialization.py

@@ -1,17 +1,78 @@
-from typing import Any
+import contextlib
+from typing import TYPE_CHECKING, Any
 
-from litestar.plugins import SerializationPlugin
+from litestar.plugins import InitPluginProtocol, SerializationPlugin
 from litestar.typing import FieldDefinition
 from sqlalchemy.orm import DeclarativeBase
 
 from advanced_alchemy.extensions.litestar.dto import SQLAlchemyDTO
 from advanced_alchemy.extensions.litestar.plugins import _slots_base
+from advanced_alchemy.utils.serialization import DEFAULT_TYPE_ENCODERS
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
 
-class SQLAlchemySerializationPlugin(SerializationPlugin, _slots_base.SlotsBase):
+    from litestar.config.app import AppConfig
+
+
+def _get_aa_type_encoders() -> "dict[type, Callable[[Any], Any]]":
+    """Return Advanced Alchemy's built-in Litestar type encoders.
+
+    These cover database-specific types (asyncpg's ``pgproto.UUID``,
+    ``uuid_utils.UUID``) that need explicit serialization to JSON-friendly
+    forms.  They are merged into ``AppConfig.type_encoders`` with lower
+    precedence than user-supplied encoders.
+    """
+    encoders: dict[type, Callable[[Any], Any]] = {**DEFAULT_TYPE_ENCODERS}
+
+    with contextlib.suppress(ImportError):
+        from asyncpg.pgproto import pgproto  # pyright: ignore[reportMissingImports]
+
+        encoders[pgproto.UUID] = str
+
+    with contextlib.suppress(ImportError):
+        import uuid_utils  # pyright: ignore[reportMissingImports]
+
+        encoders[uuid_utils.UUID] = str  # pyright: ignore[reportUnknownMemberType]
+
+    return encoders
+
+
+def _get_aa_type_decoders() -> "list[tuple[Callable[[Any], bool], Callable[[type, Any], Any]]]":
+    """Return Advanced Alchemy's built-in Litestar type decoders.
+
+    Currently covers ``uuid_utils.UUID`` for request-side parsing.  Decoders
+    are merged into ``AppConfig.type_decoders`` with lower precedence than
+    user-supplied decoders.
+    """
+    decoders: list[tuple[Callable[[Any], bool], Callable[[type, Any], Any]]] = []
+
+    with contextlib.suppress(ImportError):
+        import uuid_utils  # pyright: ignore[reportMissingImports]
+
+        decoders.append(
+            (lambda x: x is uuid_utils.UUID, lambda t, v: t(str(v)))  # pyright: ignore[reportUnknownMemberType]
+        )
+
+    return decoders
+
+
+class SQLAlchemySerializationPlugin(SerializationPlugin, InitPluginProtocol, _slots_base.SlotsBase):
     def __init__(self) -> None:
         self._type_dto_map: dict[type[DeclarativeBase], type[SQLAlchemyDTO[Any]]] = {}
 
+    def on_app_init(self, app_config: "AppConfig") -> "AppConfig":
+        """Register Advanced Alchemy's built-in type encoders and decoders.
+
+        AA encoders/decoders are added with lower precedence so user-supplied
+        ``type_encoders`` / ``type_decoders`` on the application config win.
+        """
+        aa_encoders = _get_aa_type_encoders()
+        aa_decoders = _get_aa_type_decoders()
+        app_config.type_encoders = {**aa_encoders, **(app_config.type_encoders or {})}
+        app_config.type_decoders = [*aa_decoders, *(app_config.type_decoders or [])]
+        return app_config
+
     def supports_type(self, field_definition: FieldDefinition) -> bool:
         return (
             field_definition.is_collection and field_definition.has_inner_subclass_of(DeclarativeBase)