feat(service): allow delete_many to accept model instances (#654) (#752)

## Summary
`delete_many` previously accepted only primary-key values; passing model
instances raised `invalid input syntax for type uuid: "<Model object
...>"`. It now also accepts model instances, with **per-item detection**
so a single call may mix raw IDs and instances.

## Change
- `SQLAlchemyAsyncRepositoryService.delete_many` (+ unasyncd-generated
sync twin) normalizes each item before delegating:
- model instance → PK extracted via existing repo helpers
(`get_id_attribute_value`, or `get_primary_key_value` for composite
keys)
  - raw value → passed through unchanged
- Purely additive; no existing caller behavior changes.

## Tests
- `test_service_delete_many_accepts_instances` (list of instances)
- `test_service_delete_many_accepts_mixed_instances_and_ids` (mixed)
- Verified failing before / passing after on sqlite (async + sync, uuid
+ bigint); existing delete + composite-PK tests still green.

Closes #654

Author: cofin

advanced_alchemy/service/_async.py

@@ -27,7 +27,7 @@
 )
 from advanced_alchemy.repository._util import LoadSpec, model_from_dict
 from advanced_alchemy.repository.typing import MISSING, ModelT, OrderingPair, PrimaryKeyType, SQLAlchemyAsyncRepositoryT
-from advanced_alchemy.service._util import ResultConverter
+from advanced_alchemy.service._util import ResultConverter, resolve_item_ids
 from advanced_alchemy.utils.dataclass import Empty, EmptyType
 from advanced_alchemy.utils.deprecation import warn_deprecation
 from advanced_alchemy.utils.serialization import (
@@ -1337,6 +1337,8 @@ async def delete_many(
             item_ids: List of identifiers of instances to be deleted.
                 For single primary key models, pass a list of scalar values.
                 For composite primary key models, pass a list of tuples or dicts.
+                Model instances may also be passed in place of identifiers, and the list
+                may mix instances with raw identifier values.
             auto_expunge: Remove object from session before returning.
             auto_commit: Commit objects before returning.
             id_attribute: Allows customization of the unique identifier to use for model fetching.
@@ -1377,7 +1379,12 @@ async def delete_many(
         return cast(
             "Sequence[ModelT]",
             await self.repository.delete_many(
-                item_ids=item_ids,
+                item_ids=resolve_item_ids(
+                    item_ids,
+                    model_type=self.model_type,
+                    repository=self.repository,
+                    id_attribute=id_attribute,
+                ),
                 auto_commit=auto_commit,
                 auto_expunge=auto_expunge,
                 id_attribute=id_attribute,

advanced_alchemy/service/_sync.py

@@ -26,7 +26,7 @@
 from advanced_alchemy.repository import SQLAlchemySyncQueryRepository
 from advanced_alchemy.repository._util import LoadSpec, model_from_dict
 from advanced_alchemy.repository.typing import MISSING, ModelT, OrderingPair, PrimaryKeyType, SQLAlchemySyncRepositoryT
-from advanced_alchemy.service._util import ResultConverter
+from advanced_alchemy.service._util import ResultConverter, resolve_item_ids
 from advanced_alchemy.utils.dataclass import Empty, EmptyType
 from advanced_alchemy.utils.deprecation import warn_deprecation
 from advanced_alchemy.utils.serialization import (
@@ -1336,6 +1336,8 @@ def delete_many(
             item_ids: List of identifiers of instances to be deleted.
                 For single primary key models, pass a list of scalar values.
                 For composite primary key models, pass a list of tuples or dicts.
+                Model instances may also be passed in place of identifiers, and the list
+                may mix instances with raw identifier values.
             auto_expunge: Remove object from session before returning.
             auto_commit: Commit objects before returning.
             id_attribute: Allows customization of the unique identifier to use for model fetching.
@@ -1376,7 +1378,12 @@ def delete_many(
         return cast(
             "Sequence[ModelT]",
             self.repository.delete_many(
-                item_ids=item_ids,
+                item_ids=resolve_item_ids(
+                    item_ids,
+                    model_type=self.model_type,
+                    repository=self.repository,
+                    id_attribute=id_attribute,
+                ),
                 auto_commit=auto_commit,
                 auto_expunge=auto_expunge,
                 id_attribute=id_attribute,

advanced_alchemy/service/_util.py

@@ -14,6 +14,7 @@
 
 from advanced_alchemy.exceptions import AdvancedAlchemyError
 from advanced_alchemy.filters import LimitOffset, StatementFilter
+from advanced_alchemy.repository.typing import PrimaryKeyType
 from advanced_alchemy.service.pagination import OffsetPagination
 from advanced_alchemy.typing import (
     ATTRS_INSTALLED,
@@ -41,7 +42,7 @@
     from advanced_alchemy.base import ModelProtocol
     from advanced_alchemy.repository.typing import ModelOrRowMappingT
 
-__all__ = ("ResultConverter", "find_filter")
+__all__ = ("ResultConverter", "find_filter", "resolve_item_ids")
 
 DEFAULT_TYPE_DECODERS = [  # pyright: ignore[reportUnknownVariableType]
     (lambda x: x is UUID, lambda t, v: t(v.hex)),  # pyright: ignore[reportUnknownLambdaType,reportUnknownMemberType]
@@ -71,6 +72,28 @@ def find_filter(
     )
 
 
+def resolve_item_ids(
+    item_ids: list[PrimaryKeyType],
+    *,
+    model_type: type[Any],
+    repository: Any,
+    id_attribute: Any = None,
+) -> list[PrimaryKeyType]:
+    """Resolve model instances in ``item_ids`` without copying id-only input."""
+    resolved_item_ids: Optional[list[PrimaryKeyType]] = None
+    for index, item in enumerate(item_ids):
+        if isinstance(item, model_type):
+            if resolved_item_ids is None:
+                resolved_item_ids = item_ids[:index]
+            if repository.has_composite_pk:
+                resolved_item_ids.append(repository.get_primary_key_value(item))
+            else:
+                resolved_item_ids.append(repository.get_id_attribute_value(item=item, id_attribute=id_attribute))
+        elif resolved_item_ids is not None:
+            resolved_item_ids.append(item)
+    return item_ids if resolved_item_ids is None else resolved_item_ids
+
+
 class ResultConverter:
     """Simple mixin to help convert to a paginated response model.
 

tests/integration/test_repository.py

@@ -562,6 +562,41 @@ async def test_service_delete_method(seeded_test_session_async: "tuple[AsyncSess
     assert len(remaining_authors) == 1
 
 
+async def test_service_delete_many_accepts_instances(
+    seeded_test_session_async: "tuple[AsyncSession, dict[str, type]]",
+) -> None:
+    """Test service delete_many accepts model instances as well as raw primary keys."""
+    author_service = get_service_from_session(seeded_test_session_async, "author")
+
+    authors = await maybe_async(author_service.get_many())
+    assert len(authors) == 2
+
+    deleted = await maybe_async(author_service.delete_many(list(authors)))
+    assert len(deleted) == 2
+    assert {a.id for a in deleted} == {a.id for a in authors}
+
+    remaining = await maybe_async(author_service.get_many())
+    assert len(remaining) == 0
+
+
+async def test_service_delete_many_accepts_mixed_instances_and_ids(
+    seeded_test_session_async: "tuple[AsyncSession, dict[str, type]]",
+) -> None:
+    """Test service delete_many accepts a mixed list of model instances and raw primary keys."""
+    author_service = get_service_from_session(seeded_test_session_async, "author")
+
+    authors = await maybe_async(author_service.get_many())
+    assert len(authors) == 2
+
+    mixed = [authors[0], authors[1].id]
+    deleted = await maybe_async(author_service.delete_many(mixed))
+    assert len(deleted) == 2
+    assert {a.id for a in deleted} == {a.id for a in authors}
+
+    remaining = await maybe_async(author_service.get_many())
+    assert len(remaining) == 0
+
+
 # Additional filter tests
 async def test_repo_filter_before_after(seeded_test_session_async: "tuple[AsyncSession, dict[str, type]]") -> None:
     """Test repository with BeforeAfter filter."""
@@ -1174,6 +1209,29 @@ async def test_composite_pk_delete_many_by_dicts(
         await maybe_async(user_role_repo.get((2, 10)))
 
 
+async def test_composite_pk_service_delete_many_accepts_mixed_instances_and_ids(
+    seeded_test_session_async: "tuple[AsyncSession, dict[str, type]]",
+) -> None:
+    """Test service delete_many accepts mixed model instances and raw composite keys."""
+    session, models = seeded_test_session_async
+    if "user_role" not in models:
+        pytest.skip("user_role model not available")
+
+    user_role_service = create_service(session, models["user_role"])
+
+    roles = await maybe_async(user_role_service.get_many())
+    assert len(roles) == 3
+
+    mixed = [roles[0], (roles[1].user_id, roles[1].role_id)]
+    deleted = await maybe_async(user_role_service.delete_many(mixed))
+
+    assert len(deleted) == 2
+    assert {(role.user_id, role.role_id) for role in deleted} == {
+        (roles[0].user_id, roles[0].role_id),
+        (roles[1].user_id, roles[1].role_id),
+    }
+
+
 async def test_composite_pk_count(
     seeded_test_session_async: "tuple[AsyncSession, dict[str, type]]",
 ) -> None:

tests/unit/test_service_to_model_flow.py

@@ -1,7 +1,8 @@
-"""Unit tests for service.update() model conversion flow.
+"""Unit tests for service model conversion flow.
 
 These tests verify that update input types are routed through to_model(data, "update")
-and the update lifecycle hook before persistence.
+and the update lifecycle hook before persistence. They also cover service-level
+input normalization before repository delegation.
 """
 
 from __future__ import annotations
@@ -17,6 +18,7 @@
 from advanced_alchemy.base import UUIDAuditBase
 from advanced_alchemy.repository import SQLAlchemyAsyncRepository, SQLAlchemySyncRepository
 from advanced_alchemy.repository._util import get_primary_key_info
+from advanced_alchemy.repository.typing import PrimaryKeyType
 from advanced_alchemy.service import SchemaDumpConfig, SQLAlchemyAsyncRepositoryService, SQLAlchemySyncRepositoryService
 from advanced_alchemy.utils.serialization import ATTRS_INSTALLED, MSGSPEC_INSTALLED, PYDANTIC_INSTALLED, ModelDictT
 
@@ -141,6 +143,24 @@ def to_model_on_update(self, data: ModelDictT[MockModel]) -> ModelDictT[MockMode
 # Tests for async service
 
 
+@pytest.mark.asyncio
+async def test_delete_many_passes_id_only_input_through_without_copying() -> None:
+    """Id-only delete_many() input should keep the existing bulk-delete fast path."""
+    service = TrackingService()
+    captured: dict[str, Any] = {}
+
+    async def delete_many(item_ids: list[Any], **_: Any) -> list[MockModel]:
+        captured["item_ids"] = item_ids
+        return []
+
+    service.repository.delete_many = AsyncMock(side_effect=delete_many)  # type: ignore[method-assign]
+
+    item_ids: list[PrimaryKeyType] = ["first-id", "second-id"]
+    await service.delete_many(item_ids)
+
+    assert captured["item_ids"] is item_ids
+
+
 @pytest.mark.asyncio
 async def test_update_dict_calls_to_model_with_operation() -> None:
     """Test that update() with dict data calls to_model(data, 'update')."""
@@ -358,6 +378,43 @@ async def test_update_propagates_with_for_update_flag() -> None:
 # Tests for sync service
 
 
+def test_sync_delete_many_passes_id_only_input_through_without_copying() -> None:
+    """Sync id-only delete_many() input should keep the existing bulk-delete fast path."""
+    service = TrackingSyncService()
+    captured: dict[str, Any] = {}
+
+    def delete_many(item_ids: list[Any], **_: Any) -> list[MockModel]:
+        captured["item_ids"] = item_ids
+        return []
+
+    service.repository.delete_many = MagicMock(side_effect=delete_many)  # type: ignore[method-assign]
+
+    item_ids: list[PrimaryKeyType] = ["first-id", "second-id"]
+    service.delete_many(item_ids)
+
+    assert captured["item_ids"] is item_ids
+
+
+def test_sync_delete_many_resolves_model_instances_before_delegating() -> None:
+    """Sync delete_many() should resolve model instances to primary key values."""
+    service = TrackingSyncService()
+    captured: dict[str, Any] = {}
+
+    def delete_many(item_ids: list[Any], **_: Any) -> list[MockModel]:
+        captured["item_ids"] = item_ids
+        return []
+
+    service.repository.delete_many = MagicMock(side_effect=delete_many)  # type: ignore[method-assign]
+
+    model = MockModel()
+    model.id = "model-id"  # type: ignore[assignment]
+    item_ids = cast("list[PrimaryKeyType]", [model, "raw-id"])
+    service.delete_many(item_ids)
+
+    assert captured["item_ids"] == ["model-id", "raw-id"]
+    assert captured["item_ids"] is not item_ids
+
+
 def test_sync_update_dict_calls_to_model_with_operation() -> None:
     """Test that sync update() with dict data calls to_model(data, 'update')."""
     service = TrackingSyncService()