feat: deprecate list()/list_and_count() (#706)

## Summary

- Renames `list()` → `get_many()` and `list_and_count()` → `get_many_and_count()` across repository, service, memory repo, query repo, and cache manager layers
- Old names preserved as deprecation wrappers using `warn_deprecation()`, scheduled for removal in 2.0

Author: cofin

README.md

@@ -124,7 +124,7 @@ with db.get_session() as db_session:
     print(f"Created {len(objs)} new objects.")
 
     # 2) Select paginated data and total row count.  Pass additional filters as kwargs
-    created_objs, total_objs = repo.list_and_count(LimitOffset(limit=10, offset=0), name="Cody")
+    created_objs, total_objs = repo.get_many_and_count(LimitOffset(limit=10, offset=0), name="Cody")
     print(f"Selected {len(created_objs)} records out of a total of {total_objs}.")
 
     # 3) Let's remove the batch of records selected.
@@ -190,7 +190,7 @@ with db.get_session() as db_session:
     print(f"Created {len(objs)} new objects.")
 
     # 2) Select paginated data and total row count.  Pass additional filters as kwargs
-    created_objs, total_objs = service.list_and_count(LimitOffset(limit=10, offset=0), name="Cody")
+    created_objs, total_objs = service.get_many_and_count(LimitOffset(limit=10, offset=0), name="Cody")
     print(f"Selected {len(created_objs)} records out of a total of {total_objs}.")
 
     # 3) Let's remove the batch of records selected.

advanced_alchemy/alembic/utils.py

@@ -115,7 +115,7 @@ def _dump_table_sync(session: "AbstractContextManager[Session]") -> None:
                     (SQLAlchemySyncRepository,),
                     exec_body=lambda ns, model=model: ns.setdefault("model_type", model),  # type: ignore[misc]
                 )
-                json_path.write_text(encode_json([model_to_dict(row) for row in repo(session=_session).list()]))
+                json_path.write_text(encode_json([model_to_dict(row) for row in repo(session=_session).get_many()]))
 
     async def _dump_table_async(session: "AbstractAsyncContextManager[AsyncSession]") -> None:
         from advanced_alchemy.repository import SQLAlchemyAsyncRepository
@@ -133,7 +133,9 @@ async def _dump_table_async(session: "AbstractAsyncContextManager[AsyncSession]"
                     (SQLAlchemyAsyncRepository,),
                     exec_body=lambda ns, model=model: ns.setdefault("model_type", model),  # type: ignore[misc]
                 )
-                json_path.write_text(encode_json([model_to_dict(row) for row in await repo(session=_session).list()]))
+                json_path.write_text(
+                    encode_json([model_to_dict(row) for row in await repo(session=_session).get_many()])
+                )
 
     await async_(dump_dir.mkdir)(exist_ok=True)
 

advanced_alchemy/cache/manager.py

@@ -12,6 +12,7 @@
 
 from advanced_alchemy.cache._null import NO_VALUE, NullRegion, SyncCacheRegionProtocol
 from advanced_alchemy.cache.serializers import default_deserializer, default_serializer
+from advanced_alchemy.utils.deprecation import warn_deprecation
 from advanced_alchemy.utils.sync_tools import async_
 
 if TYPE_CHECKING:
@@ -437,7 +438,7 @@ def get_model_version_sync(self, model_name: str) -> str:
 
         return "0"
 
-    def get_list_sync(self, key: str, model_class: type[T]) -> Optional[list[T]]:
+    def get_many_sync(self, key: str, model_class: type[T]) -> Optional[list[T]]:
         """Get a cached list of entities (sync).
 
         The list is stored as base64-encoded serialized entity payloads.
@@ -470,7 +471,7 @@ def get_list_sync(self, key: str, model_class: type[T]) -> Optional[list[T]]:
             return None
         return results
 
-    def set_list_sync(self, key: str, items: list[Any]) -> None:
+    def set_many_sync(self, key: str, items: list[Any]) -> None:
         """Cache a list of entities (sync).
 
         Args:
@@ -484,7 +485,7 @@ def set_list_sync(self, key: str, items: list[Any]) -> None:
         except Exception:
             logger.exception("Failed to serialize cached list for key %s", key)
 
-    def get_list_and_count_sync(self, key: str, model_class: type[T]) -> Optional[tuple[list[T], int]]:
+    def get_many_and_count_sync(self, key: str, model_class: type[T]) -> Optional[tuple[list[T], int]]:
         """Get a cached list+count payload (sync)."""
         cached = self.get_sync(key)
         if cached is DOGPILE_NO_VALUE or cached is NO_VALUE:
@@ -513,7 +514,7 @@ def get_list_and_count_sync(self, key: str, model_class: type[T]) -> Optional[tu
             return None
         return results, count_raw
 
-    def set_list_and_count_sync(self, key: str, items: list[Any], count: int) -> None:
+    def set_many_and_count_sync(self, key: str, items: list[Any], count: int) -> None:
         """Cache a list+count payload (sync)."""
         serializer = self.config.serializer or default_serializer
         try:
@@ -525,6 +526,66 @@ def set_list_and_count_sync(self, key: str, items: list[Any], count: int) -> Non
         except Exception:
             logger.exception("Failed to serialize cached list_and_count for key %s", key)
 
+    def get_list_sync(self, key: str, model_class: type[T]) -> Optional[list[T]]:
+        """Get a cached list of entities (sync).
+
+        .. deprecated:: 1.10.0
+            Use :meth:`get_many_sync` instead.
+        """
+        warn_deprecation(
+            version="1.10.0",
+            deprecated_name="get_list_sync",
+            kind="method",
+            removal_in="2.0.0",
+            alternative="get_many_sync",
+        )
+        return self.get_many_sync(key, model_class)
+
+    def set_list_sync(self, key: str, items: list[Any]) -> None:
+        """Cache a list of entities (sync).
+
+        .. deprecated:: 1.10.0
+            Use :meth:`set_many_sync` instead.
+        """
+        warn_deprecation(
+            version="1.10.0",
+            deprecated_name="set_list_sync",
+            kind="method",
+            removal_in="2.0.0",
+            alternative="set_many_sync",
+        )
+        self.set_many_sync(key, items)
+
+    def get_list_and_count_sync(self, key: str, model_class: type[T]) -> Optional[tuple[list[T], int]]:
+        """Get a cached list+count payload (sync).
+
+        .. deprecated:: 1.10.0
+            Use :meth:`get_many_and_count_sync` instead.
+        """
+        warn_deprecation(
+            version="1.10.0",
+            deprecated_name="get_list_and_count_sync",
+            kind="method",
+            removal_in="2.0.0",
+            alternative="get_many_and_count_sync",
+        )
+        return self.get_many_and_count_sync(key, model_class)
+
+    def set_list_and_count_sync(self, key: str, items: list[Any], count: int) -> None:
+        """Cache a list+count payload (sync).
+
+        .. deprecated:: 1.10.0
+            Use :meth:`set_many_and_count_sync` instead.
+        """
+        warn_deprecation(
+            version="1.10.0",
+            deprecated_name="set_list_and_count_sync",
+            kind="method",
+            removal_in="2.0.0",
+            alternative="set_many_and_count_sync",
+        )
+        self.set_many_and_count_sync(key, items, count)
+
     def singleflight_sync(self, key: str, creator: Callable[[], T]) -> T:
         """Coalesce concurrent sync cache misses per-process.
 
@@ -713,21 +774,81 @@ async def get_model_version_async(self, model_name: str) -> str:
         """
         return await async_(self.get_model_version_sync)(model_name)
 
-    async def get_list_async(self, key: str, model_class: type[T]) -> Optional[list[T]]:
+    async def get_many_async(self, key: str, model_class: type[T]) -> Optional[list[T]]:
         """Get a cached list of entities (async)."""
-        return await async_(self.get_list_sync)(key, model_class)
+        return await async_(self.get_many_sync)(key, model_class)
 
-    async def set_list_async(self, key: str, items: list[Any]) -> None:
+    async def set_many_async(self, key: str, items: list[Any]) -> None:
         """Cache a list of entities (async)."""
-        await async_(self.set_list_sync)(key, items)
+        await async_(self.set_many_sync)(key, items)
 
-    async def get_list_and_count_async(self, key: str, model_class: type[T]) -> Optional[tuple[list[T], int]]:
+    async def get_many_and_count_async(self, key: str, model_class: type[T]) -> Optional[tuple[list[T], int]]:
         """Get a cached list+count payload (async)."""
-        return await async_(self.get_list_and_count_sync)(key, model_class)
+        return await async_(self.get_many_and_count_sync)(key, model_class)
 
-    async def set_list_and_count_async(self, key: str, items: list[Any], count: int) -> None:
+    async def set_many_and_count_async(self, key: str, items: list[Any], count: int) -> None:
         """Cache a list+count payload (async)."""
-        await async_(self.set_list_and_count_sync)(key, items, count)
+        await async_(self.set_many_and_count_sync)(key, items, count)
+
+    async def get_list_async(self, key: str, model_class: type[T]) -> Optional[list[T]]:
+        """Get a cached list of entities (async).
+
+        .. deprecated:: 1.10.0
+            Use :meth:`get_many_async` instead.
+        """
+        warn_deprecation(
+            version="1.10.0",
+            deprecated_name="get_list_async",
+            kind="method",
+            removal_in="2.0.0",
+            alternative="get_many_async",
+        )
+        return await self.get_many_async(key, model_class)
+
+    async def set_list_async(self, key: str, items: list[Any]) -> None:
+        """Cache a list of entities (async).
+
+        .. deprecated:: 1.10.0
+            Use :meth:`set_many_async` instead.
+        """
+        warn_deprecation(
+            version="1.10.0",
+            deprecated_name="set_list_async",
+            kind="method",
+            removal_in="2.0.0",
+            alternative="set_many_async",
+        )
+        await self.set_many_async(key, items)
+
+    async def get_list_and_count_async(self, key: str, model_class: type[T]) -> Optional[tuple[list[T], int]]:
+        """Get a cached list+count payload (async).
+
+        .. deprecated:: 1.10.0
+            Use :meth:`get_many_and_count_async` instead.
+        """
+        warn_deprecation(
+            version="1.10.0",
+            deprecated_name="get_list_and_count_async",
+            kind="method",
+            removal_in="2.0.0",
+            alternative="get_many_and_count_async",
+        )
+        return await self.get_many_and_count_async(key, model_class)
+
+    async def set_list_and_count_async(self, key: str, items: list[Any], count: int) -> None:
+        """Cache a list+count payload (async).
+
+        .. deprecated:: 1.10.0
+            Use :meth:`set_many_and_count_async` instead.
+        """
+        warn_deprecation(
+            version="1.10.0",
+            deprecated_name="set_list_and_count_async",
+            kind="method",
+            removal_in="2.0.0",
+            alternative="set_many_and_count_async",
+        )
+        await self.set_many_and_count_async(key, items, count)
 
     async def singleflight_async(self, key: str, creator: Callable[[], Coroutine[Any, Any, T]]) -> T:
         """Coalesce concurrent async cache misses per-process.

advanced_alchemy/filters.py

@@ -397,7 +397,7 @@ class NullFilter(StatementFilter):
 
             # Find records where email_verified_at is NULL
             null_filter = NullFilter("email_verified_at")
-            unverified = await repo.list(null_filter)
+            unverified = await repo.get_many(null_filter)
 
         With multiple filters::
 
@@ -411,7 +411,7 @@ class NullFilter(StatementFilter):
                 NullFilter("email_verified_at"),
                 CollectionFilter("role", ["admin", "moderator"]),
             ]
-            results = await repo.list(*filters)
+            results = await repo.get_many(*filters)
 
     See Also:
         - :class:`NotNullFilter`: Filter for NOT NULL values
@@ -450,7 +450,7 @@ class NotNullFilter(StatementFilter):
 
             # Find records where email_verified_at is NOT NULL
             not_null_filter = NotNullFilter("email_verified_at")
-            verified = await repo.list(not_null_filter)
+            verified = await repo.get_many(not_null_filter)
 
         With multiple filters::
 
@@ -464,7 +464,7 @@ class NotNullFilter(StatementFilter):
                 NotNullFilter("email_verified_at"),
                 CollectionFilter("role", ["admin", "moderator"]),
             ]
-            results = await repo.list(*filters)
+            results = await repo.get_many(*filters)
 
     See Also:
         - :class:`NullFilter`: Filter for NULL values