fix(typing): deprecate DictProtocol public export (#757)

## Summary

Closes #583.

- Deprecates `advanced_alchemy.typing.DictProtocol` starting in 1.11.0
and schedules removal for 2.0.0.
- Keeps the compatibility object available through 1.x with lazy warning
behavior instead of binding the public export at import time.
- Removes the runtime serialization dependency on the public protocol
while preserving the `hasattr(obj, "__dict__")` behavior from #579.
- Adds regression coverage for `has_dict_attribute()`, `schema_dump()`
fallback behavior, direct typing import warnings, and the deprecated
service typing shim.
- Adds a 1.11.0 changelog entry for the deprecation.

Author: cofin

advanced_alchemy/typing.py

@@ -1,10 +1,13 @@
+# pyright: reportUnsupportedDunderAll=false
 """Public type shims for optional dependencies.
 
 Re-exports foundational stub types so that internal and external code
 can ``from advanced_alchemy.typing import SQLModelBase`` (or any other
 shim) without reaching into private modules.
 """
 
+from typing import Any
+
 from advanced_alchemy._typing import (
     ATTRS_INSTALLED,
     CATTRS_INSTALLED,
@@ -20,7 +23,6 @@
     BaseModel,
     BaseModelLike,
     DataclassProtocol,
-    DictProtocol,
     DTOData,
     DTODataLike,
     FailFast,
@@ -41,7 +43,7 @@
     convert,
 )
 
-__all__ = (
+__all__ = (  # noqa: F822
     "ATTRS_INSTALLED",
     "CATTRS_INSTALLED",
     "LITESTAR_INSTALLED",
@@ -76,3 +78,21 @@
     "cattrs_unstructure",
     "convert",
 )
+
+
+def __getattr__(name: str) -> Any:
+    if name != "DictProtocol":
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)
+
+    from advanced_alchemy._typing import DictProtocol
+    from advanced_alchemy.utils.deprecation import warn_deprecation
+
+    warn_deprecation(
+        version="1.11.0",
+        removal_in="2.0.0",
+        deprecated_name=f"{__name__}.DictProtocol",
+        kind="import",
+        alternative="advanced_alchemy.utils.serialization.has_dict_attribute",
+    )
+    return DictProtocol

advanced_alchemy/utils/serialization.py

@@ -74,7 +74,6 @@
     AttrsLike,
     BaseModel,
     BaseModelLike,
-    DictProtocol,
     DTOData,
     DTODataLike,
     FailFast,
@@ -200,6 +199,10 @@
 """Type alias for bulk model dictionaries."""
 
 
+class _HasDictAttribute(Protocol):
+    __dict__: dict[str, Any]
+
+
 @dataclass(frozen=True)
 class SchemaDumpConfig:
     """Configuration for dumping schema-like service input data."""
@@ -370,7 +373,7 @@ def is_dict(v: Any) -> TypeGuard[dict[str, Any]]:
     return isinstance(v, dict)
 
 
-def has_dict_attribute(obj: Any) -> "TypeGuard[DictProtocol]":
+def has_dict_attribute(obj: Any) -> "TypeGuard[_HasDictAttribute]":
     """Check if an object has a __dict__ attribute."""
     return obj is not None and hasattr(obj, "__dict__")
 

docs/changelog.rst

@@ -17,6 +17,15 @@
         excluding unset values, ``None`` values, defaults, and sentinel values
         while preserving the existing partial-update defaults.
 
+    .. change:: deprecate DictProtocol
+        :type: misc
+        :issue: 583
+
+        Deprecates ``advanced_alchemy.typing.DictProtocol`` and schedules it
+        for removal in 2.0. Runtime code should rely on ``has_dict_attribute()``
+        or direct ``__dict__`` duck typing instead of Protocol-based instance
+        checks.
+
     .. change:: add choices and boolean filters
         :type: feature
         :pr: 723

tests/unit/test_utils/test_serialization.py

@@ -7,6 +7,7 @@
 import json
 import threading
 import time
+import warnings
 from decimal import Decimal
 from enum import Enum
 from ipaddress import IPv4Address, IPv4Interface, IPv4Network, IPv6Address, IPv6Interface, IPv6Network
@@ -417,6 +418,62 @@ def __init__(self) -> None:
     assert schema_dump(AttrsLike()) == {"name": "Ada"}
 
 
+@pytest.mark.parametrize(
+    "value",
+    [
+        None,
+        1,
+        [1, 2],
+        {},
+    ],
+)
+def test_has_dict_attribute_rejects_values_without_instance_dict(value: Any) -> None:
+    assert not serialization.has_dict_attribute(value)
+
+
+def test_has_dict_attribute_accepts_plain_object() -> None:
+    class PlainObject:
+        def __init__(self) -> None:
+            self.name = "Ada"
+
+    assert serialization.has_dict_attribute(PlainObject())
+
+
+def test_has_dict_attribute_rejects_slots_only_object() -> None:
+    class SlotsOnlyObject:
+        __slots__ = ("name",)
+
+        def __init__(self) -> None:
+            self.name = "Ada"
+
+    assert not serialization.has_dict_attribute(SlotsOnlyObject())
+
+
+def test_schema_dump_uses_instance_dict_fallback_for_plain_objects() -> None:
+    class PlainObject:
+        def __init__(self) -> None:
+            self.name = "Ada"
+
+    assert schema_dump(PlainObject()) == {"name": "Ada"}
+
+
+def test_schema_dump_passes_through_slots_only_objects() -> None:
+    class SlotsOnlyObject:
+        __slots__ = ("name",)
+
+        def __init__(self) -> None:
+            self.name = "Ada"
+
+    value = SlotsOnlyObject()
+    result: Any = schema_dump(value)
+
+    assert result is value
+
+
+def test_serialization_module_does_not_import_public_dict_protocol() -> None:
+    assert "DictProtocol" not in vars(serialization)
+
+
 @pytest.mark.parametrize(
     ("kind", "value", "expected"),
     [
@@ -978,14 +1035,34 @@ def test_legacy_service_typing_shim_emits_deprecation_warning(name: str, new_mod
     assert value is canonical
 
 
+def test_typing_dict_protocol_emits_deprecation_warning() -> None:
+    with pytest.warns(DeprecationWarning, match=r"DictProtocol.*1\.11\.0.*removed in 2\.0\.0"):
+        value = _import_attr("advanced_alchemy.typing", "DictProtocol")
+
+    assert value is _import_attr("advanced_alchemy._typing", "DictProtocol")
+
+
+def test_typing_canonical_exports_do_not_emit_deprecation_warning() -> None:
+    typing_module = importlib.import_module("advanced_alchemy.typing")
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        assert getattr(typing_module, "PYDANTIC_INSTALLED") is PYDANTIC_INSTALLED
+
+
+def test_legacy_service_typing_dict_protocol_remains_compatible() -> None:
+    with pytest.warns(DeprecationWarning, match="DictProtocol"):
+        value = _import_attr("advanced_alchemy.service.typing", "DictProtocol")
+
+    assert value is _import_attr("advanced_alchemy._typing", "DictProtocol")
+
+
 def test_legacy_service_typing_shim_unknown_attribute_raises() -> None:
     with pytest.raises(AttributeError, match="not_a_real_name"):
         _import_attr("advanced_alchemy.service.typing", "not_a_real_name")
 
 
 def test_legacy_service_typing_shim_keeps_pydantic_use_failfast() -> None:
-    import warnings
-
     import advanced_alchemy.service.typing as shim
 
     with warnings.catch_warnings():