Merge branch 'main' into claude/issue-114-20251026-0414

Author: strawgate

README.md

@@ -164,7 +164,7 @@ get(key: str, collection: str | None = None) -> dict[str, Any] | None:
 get_many(keys: list[str], collection: str | None = None) -> list[dict[str, Any] | None]:
 
 put(key: str, value: dict[str, Any], collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
-put_many(keys: list[str], values: Sequence[dict[str, Any]], collection: str | None = None, ttl: Sequence[SupportsFloat | None] | None = None) -> None:
+put_many(keys: list[str], values: Sequence[dict[str, Any]], collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
 
 delete(key: str, collection: str | None = None) -> bool:
 delete_many(keys: list[str], collection: str | None = None) -> int:

key-value/key-value-aio/src/key_value/aio/adapters/pydantic/adapter.py

@@ -82,7 +82,7 @@ async def get(self, key: str, *, collection: str | None = None) -> T | None:
 
         return None
 
-    async def get_many(self, keys: list[str], *, collection: str | None = None) -> list[T | None]:
+    async def get_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[T | None]:
         """Batch get and validate models by keys, preserving order.
 
         Returns:
@@ -110,7 +110,7 @@ async def put(self, key: str, value: T, *, collection: str | None = None, ttl: S
         await self._key_value.put(key=key, value=value_dict, collection=collection, ttl=ttl)
 
     async def put_many(
-        self, keys: list[str], values: Sequence[T], *, collection: str | None = None, ttl: Sequence[SupportsFloat | None] | None = None
+        self, keys: Sequence[str], values: Sequence[T], *, collection: str | None = None, ttl: SupportsFloat | None = None
     ) -> None:
         """Serialize and store multiple models, preserving order alignment with keys."""
         collection = collection or self._default_collection
@@ -125,7 +125,7 @@ async def delete(self, key: str, *, collection: str | None = None) -> bool:
 
         return await self._key_value.delete(key=key, collection=collection)
 
-    async def delete_many(self, keys: list[str], *, collection: str | None = None) -> int:
+    async def delete_many(self, keys: Sequence[str], *, collection: str | None = None) -> int:
         """Delete multiple models by key. Returns the count of deleted entries."""
         collection = collection or self._default_collection
 
@@ -151,7 +151,7 @@ async def ttl(self, key: str, *, collection: str | None = None) -> tuple[T | Non
 
         return (None, None)
 
-    async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> list[tuple[T | None, float | None]]:
+    async def ttl_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[tuple[T | None, float | None]]:
         """Batch get models with TTLs. Each element is (model|None, ttl_seconds|None)."""
         collection = collection or self._default_collection
 

key-value/key-value-aio/src/key_value/aio/adapters/raise_on_missing/adapter.py

@@ -50,16 +50,16 @@ async def get(
 
     @overload
     async def get_many(
-        self, keys: list[str], *, collection: str | None = None, raise_on_missing: Literal[False] = False
+        self, keys: Sequence[str], *, collection: str | None = None, raise_on_missing: Literal[False] = False
     ) -> list[dict[str, Any] | None]: ...
 
     @overload
     async def get_many(
-        self, keys: list[str], *, collection: str | None = None, raise_on_missing: Literal[True]
+        self, keys: Sequence[str], *, collection: str | None = None, raise_on_missing: Literal[True]
     ) -> list[dict[str, Any]]: ...
 
     async def get_many(
-        self, keys: list[str], *, collection: str | None = None, raise_on_missing: bool = False
+        self, keys: Sequence[str], *, collection: str | None = None, raise_on_missing: bool = False
     ) -> list[dict[str, Any]] | list[dict[str, Any] | None]:
         """Retrieve multiple values by key from the specified collection.
 
@@ -113,16 +113,16 @@ async def ttl(
 
     @overload
     async def ttl_many(
-        self, keys: list[str], *, collection: str | None = None, raise_on_missing: Literal[False] = False
+        self, keys: Sequence[str], *, collection: str | None = None, raise_on_missing: Literal[False] = False
     ) -> list[tuple[dict[str, Any] | None, float | None]]: ...
 
     @overload
     async def ttl_many(
-        self, keys: list[str], *, collection: str | None = None, raise_on_missing: Literal[True]
+        self, keys: Sequence[str], *, collection: str | None = None, raise_on_missing: Literal[True]
     ) -> list[tuple[dict[str, Any], float | None]]: ...
 
     async def ttl_many(
-        self, keys: list[str], *, collection: str | None = None, raise_on_missing: bool = False
+        self, keys: Sequence[str], *, collection: str | None = None, raise_on_missing: bool = False
     ) -> list[tuple[dict[str, Any], float | None]] | list[tuple[dict[str, Any] | None, float | None]]:
         """Retrieve multiple values and TTL information by key from the specified collection.
 
@@ -152,20 +152,21 @@ async def put(self, key: str, value: Mapping[str, Any], *, collection: str | Non
 
     async def put_many(
         self,
-        keys: list[str],
+        keys: Sequence[str],
         values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
-        ttl: Sequence[SupportsFloat | None] | None = None,
+        ttl: SupportsFloat | None = None,
     ) -> None:
         """Store multiple key-value pairs in the specified collection.
 
         Args:
             keys: The keys to store the values in.
             values: The values to store.
             collection: The collection to store keys in. If no collection is provided, it will use the default collection.
-            ttl: The optional time-to-live (expiry duration) for the key-value pairs. Defaults to no TTL. Note: The
-                backend store will convert the provided format to its own internal format.
+            ttl: The optional time-to-live (expiry duration) for all key-value pairs. The same TTL will be applied to all
+                items in the batch. Defaults to no TTL. Note: The backend store will convert the provided format to its own
+                internal format.
         """
         return await self.key_value.put_many(keys=keys, values=values, collection=collection, ttl=ttl)
 
@@ -178,7 +179,7 @@ async def delete(self, key: str, *, collection: str | None = None) -> bool:
         """
         return await self.key_value.delete(key=key, collection=collection)
 
-    async def delete_many(self, keys: list[str], *, collection: str | None = None) -> int:
+    async def delete_many(self, keys: Sequence[str], *, collection: str | None = None) -> int:
         """Delete multiple key-value pairs from the specified collection.
 
         Args:

key-value/key-value-aio/src/key_value/aio/protocols/key_value.py

@@ -57,7 +57,7 @@ async def delete(self, key: str, *, collection: str | None = None) -> bool:
         """
         ...
 
-    async def get_many(self, keys: list[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
+    async def get_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
         """Retrieve multiple values by key from the specified collection.
 
         Args:
@@ -69,7 +69,7 @@ async def get_many(self, keys: list[str], *, collection: str | None = None) -> l
         """
         ...
 
-    async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
+    async def ttl_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
         """Retrieve multiple values and TTL information by key from the specified collection.
 
         Args:
@@ -84,24 +84,25 @@ async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> l
 
     async def put_many(
         self,
-        keys: list[str],
+        keys: Sequence[str],
         values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
-        ttl: Sequence[SupportsFloat | None] | None = None,
+        ttl: SupportsFloat | None = None,
     ) -> None:
         """Store multiple key-value pairs in the specified collection.
 
         Args:
             keys: The keys to store the values in.
             values: The values to store.
             collection: The collection to store keys in. If no collection is provided, it will use the default collection.
-            ttl: The optional time-to-live (expiry duration) in seconds for the key-value pairs. Defaults to no TTL. Note: The
-                backend store will convert the provided format to its own internal format.
+            ttl: The optional time-to-live (expiry duration) in seconds for all key-value pairs. The same TTL will be applied
+                to all items in the batch. Defaults to no TTL. Note: The backend store will convert the provided format to
+                its own internal format.
         """
         ...
 
-    async def delete_many(self, keys: list[str], *, collection: str | None = None) -> int:
+    async def delete_many(self, keys: Sequence[str], *, collection: str | None = None) -> int:
         """Delete multiple key-value pairs from the specified collection.
 
         Args:

key-value/key-value-aio/src/key_value/aio/stores/base.py

@@ -12,7 +12,7 @@
 from key_value.shared.constants import DEFAULT_COLLECTION_NAME
 from key_value.shared.errors import StoreSetupError
 from key_value.shared.utils.managed_entry import ManagedEntry
-from key_value.shared.utils.time_to_live import now, prepare_ttl, prepare_ttls
+from key_value.shared.utils.time_to_live import now, prepare_ttl
 from typing_extensions import Self, override
 
 from key_value.aio.protocols.key_value import (
@@ -102,7 +102,7 @@ async def setup_collection(self, *, collection: str) -> None:
     async def _get_managed_entry(self, *, collection: str, key: str) -> ManagedEntry | None:
         """Retrieve a cache entry by key from the specified collection."""
 
-    async def _get_managed_entries(self, *, collection: str, keys: list[str]) -> list[ManagedEntry | None]:
+    async def _get_managed_entries(self, *, collection: str, keys: Sequence[str]) -> list[ManagedEntry | None]:
         """Retrieve multiple managed entries by key from the specified collection."""
 
         return [await self._get_managed_entry(collection=collection, key=key) for key in keys]
@@ -137,7 +137,7 @@ async def get(
         return dict(managed_entry.value)
 
     @override
-    async def get_many(self, keys: list[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
+    async def get_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
         collection = collection or self.default_collection
         await self.setup_collection(collection=collection)
 
@@ -159,7 +159,7 @@ async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[st
     @override
     async def ttl_many(
         self,
-        keys: list[str],
+        keys: Sequence[str],
         *,
         collection: str | None = None,
     ) -> list[tuple[dict[str, Any] | None, float | None]]:
@@ -179,7 +179,7 @@ async def _put_managed_entry(self, *, collection: str, key: str, managed_entry:
         """Store a managed entry by key in the specified collection."""
         ...
 
-    async def _put_managed_entries(self, *, collection: str, keys: list[str], managed_entries: Sequence[ManagedEntry]) -> None:
+    async def _put_managed_entries(self, *, collection: str, keys: Sequence[str], managed_entries: Sequence[ManagedEntry]) -> None:
         """Store multiple managed entries by key in the specified collection."""
 
         for key, managed_entry in zip(keys, managed_entries, strict=True):
@@ -204,8 +204,8 @@ async def put(self, key: str, value: Mapping[str, Any], *, collection: str | Non
         )
 
     def _prepare_put_many(
-        self, *, keys: list[str], values: Sequence[Mapping[str, Any]], ttl: Sequence[SupportsFloat | None] | SupportsFloat | None
-    ) -> tuple[list[str], Sequence[Mapping[str, Any]], list[float | None]]:
+        self, *, keys: Sequence[str], values: Sequence[Mapping[str, Any]], ttl: SupportsFloat | None
+    ) -> tuple[Sequence[str], Sequence[Mapping[str, Any]], float | None]:
         """Prepare multiple managed entries for a put_many operation.
 
         Inheriting classes can use this method if they need to modify a put_many operation."""
@@ -214,22 +214,18 @@ def _prepare_put_many(
             msg = "put_many called but a different number of keys and values were provided"
             raise ValueError(msg) from None
 
-        if ttl and isinstance(ttl, Sequence) and len(ttl) != len(keys):
-            msg = "put_many called but a different number of keys and ttl values were provided"
-            raise ValueError(msg) from None
-
-        ttl_for_entries: list[float | None] = prepare_ttls(t=ttl, count=len(keys))
+        ttl_for_entries: float | None = prepare_ttl(t=ttl)
 
         return (keys, values, ttl_for_entries)
 
     @override
     async def put_many(
         self,
-        keys: list[str],
+        keys: Sequence[str],
         values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
-        ttl: Sequence[SupportsFloat | None] | None = None,
+        ttl: SupportsFloat | None = None,
     ) -> None:
         """Store multiple key-value pairs in the specified collection."""
 
@@ -238,9 +234,7 @@ async def put_many(
 
         keys, values, ttl_for_entries = self._prepare_put_many(keys=keys, values=values, ttl=ttl)
 
-        managed_entries: list[ManagedEntry] = [
-            ManagedEntry(value=value, ttl=ttl_for_entries[i], created_at=now()) for i, value in enumerate(values)
-        ]
+        managed_entries: list[ManagedEntry] = [ManagedEntry(value=value, ttl=ttl_for_entries, created_at=now()) for value in values]
 
         await self._put_managed_entries(collection=collection, keys=keys, managed_entries=managed_entries)
 
@@ -249,7 +243,7 @@ async def _delete_managed_entry(self, *, key: str, collection: str) -> bool:
         """Delete a managed entry by key from the specified collection."""
         ...
 
-    async def _delete_managed_entries(self, *, keys: list[str], collection: str) -> int:
+    async def _delete_managed_entries(self, *, keys: Sequence[str], collection: str) -> int:
         """Delete multiple managed entries by key from the specified collection."""
 
         deleted_count: int = 0
@@ -268,7 +262,7 @@ async def delete(self, key: str, *, collection: str | None = None) -> bool:
         return await self._delete_managed_entry(key=key, collection=collection)
 
     @override
-    async def delete_many(self, keys: list[str], *, collection: str | None = None) -> int:
+    async def delete_many(self, keys: Sequence[str], *, collection: str | None = None) -> int:
         """Delete multiple managed entries by key from the specified collection."""
         collection = collection or self.default_collection
         await self.setup_collection(collection=collection)

key-value/key-value-aio/src/key_value/aio/stores/memory/store.py

@@ -55,7 +55,7 @@ def _memory_cache_ttu(_key: Any, value: MemoryCacheEntry, now: float) -> float:
     return float(expiration_epoch)
 
 
-def _memory_cache_getsizeof(value: MemoryCacheEntry) -> int:  # pyright: ignore[reportUnusedParameter]  # noqa: ARG001
+def _memory_cache_getsizeof(value: MemoryCacheEntry) -> int:  # pyright: ignore[reportUnusedParameter]
     """Return size of cache entry (always 1 for entry counting)."""
     return 1
 

key-value/key-value-aio/src/key_value/aio/wrappers/base.py

@@ -16,15 +16,15 @@ async def get(self, key: str, *, collection: str | None = None) -> dict[str, Any
         return await self.key_value.get(collection=collection, key=key)
 
     @override
-    async def get_many(self, keys: list[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
+    async def get_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
         return await self.key_value.get_many(collection=collection, keys=keys)
 
     @override
     async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[str, Any] | None, float | None]:
         return await self.key_value.ttl(collection=collection, key=key)
 
     @override
-    async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
+    async def ttl_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
         return await self.key_value.ttl_many(collection=collection, keys=keys)
 
     @override
@@ -34,11 +34,11 @@ async def put(self, key: str, value: Mapping[str, Any], *, collection: str | Non
     @override
     async def put_many(
         self,
-        keys: list[str],
+        keys: Sequence[str],
         values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
-        ttl: Sequence[SupportsFloat | None] | None = None,
+        ttl: SupportsFloat | None = None,
     ) -> None:
         return await self.key_value.put_many(keys=keys, values=values, collection=collection, ttl=ttl)
 
@@ -47,5 +47,5 @@ async def delete(self, key: str, *, collection: str | None = None) -> bool:
         return await self.key_value.delete(collection=collection, key=key)
 
     @override
-    async def delete_many(self, keys: list[str], *, collection: str | None = None) -> int:
+    async def delete_many(self, keys: Sequence[str], *, collection: str | None = None) -> int:
         return await self.key_value.delete_many(keys=keys, collection=collection)

key-value/key-value-aio/src/key_value/aio/wrappers/compression/wrapper.py

@@ -116,7 +116,7 @@ async def get(self, key: str, *, collection: str | None = None) -> dict[str, Any
         return self._decompress_value(value)
 
     @override
-    async def get_many(self, keys: list[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
+    async def get_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
         values = await self.key_value.get_many(keys=keys, collection=collection)
         return [self._decompress_value(value) for value in values]
 
@@ -126,7 +126,7 @@ async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[st
         return self._decompress_value(value), ttl
 
     @override
-    async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
+    async def ttl_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
         results = await self.key_value.ttl_many(keys=keys, collection=collection)
         return [(self._decompress_value(value), ttl) for value, ttl in results]
 
@@ -138,11 +138,11 @@ async def put(self, key: str, value: Mapping[str, Any], *, collection: str | Non
     @override
     async def put_many(
         self,
-        keys: list[str],
+        keys: Sequence[str],
         values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
-        ttl: Sequence[SupportsFloat | None] | None = None,
+        ttl: SupportsFloat | None = None,
     ) -> None:
         compressed_values = [self._compress_value(dict(value)) for value in values]
         return await self.key_value.put_many(keys=keys, values=compressed_values, collection=collection, ttl=ttl)