refactor: switch key input parameters from list to Sequence (#119)

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: William Easton <strawgate@users.noreply.github.com>

Author: 3 people

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: Sequence[SupportsFloat | None] | 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,7 +152,7 @@ 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,
@@ -178,7 +178,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,7 +84,7 @@ 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,
@@ -101,7 +101,7 @@ async def put_many(
         """
         ...
 
-    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

@@ -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: Sequence[SupportsFloat | None] | SupportsFloat | None
+    ) -> tuple[Sequence[str], Sequence[Mapping[str, Any]], list[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."""
@@ -225,7 +225,7 @@ def _prepare_put_many(
     @override
     async def put_many(
         self,
-        keys: list[str],
+        keys: Sequence[str],
         values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
@@ -249,7 +249,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 +268,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/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,7 +34,7 @@ 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,
@@ -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,7 +138,7 @@ 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,

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

@@ -143,7 +143,7 @@ async def get(self, key: str, *, collection: str | None = None) -> dict[str, Any
         return self._decrypt_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._decrypt_value(value) for value in values]
 
@@ -153,7 +153,7 @@ async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[st
         return self._decrypt_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._decrypt_value(value), ttl) for value, ttl in results]
 
@@ -165,7 +165,7 @@ 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,

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

@@ -50,7 +50,7 @@ async def get(self, key: str, *, collection: str | None = None) -> dict[str, Any
             return await self.fallback_key_value.get(key=key, collection=collection)
 
     @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]:
         try:
             return await self.primary_key_value.get_many(keys=keys, collection=collection)
         except self.fallback_on:
@@ -64,7 +64,7 @@ async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[st
             return await self.fallback_key_value.ttl(key=key, collection=collection)
 
     @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]]:
         try:
             return await self.primary_key_value.ttl_many(keys=keys, collection=collection)
         except self.fallback_on:
@@ -83,7 +83,7 @@ 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,
@@ -108,7 +108,7 @@ async def delete(self, key: str, *, collection: str | None = None) -> bool:
             return await self.primary_key_value.delete(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:
         if self.write_to_fallback:
             try:
                 return await self.primary_key_value.delete_many(keys=keys, collection=collection)

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

@@ -87,7 +87,7 @@ 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,