refactor: switch key input parameters from list to Sequence

Switch all key input parameters in bulk operations from list[str] to
Sequence[str] while keeping return types as list[str]. This follows the
Liskov Substitution Principle - accept more general types as inputs,
return more specific types as outputs.

This change completes the pattern started in #103 (Mapping for values)
and improves the API's flexibility by accepting any sequence-like object
(list, tuple, etc.) as input while maintaining backward compatibility.
All existing code continues to work since list is a subclass of Sequence.

Changes:
- Updated AsyncKeyValueProtocol with Sequence for bulk operation keys
- Updated BaseStore and all wrapper implementations
- Updated adapters
- Updated shared utility functions
- Regenerated sync library

Fixes #116

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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/stores/elasticsearch/store.py

@@ -1,5 +1,8 @@
 from typing import TYPE_CHECKING, Any, overload
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 from key_value.shared.utils.compound import compound_key
 from key_value.shared.utils.managed_entry import ManagedEntry, load_from_json
 from key_value.shared.utils.sanitize import (
@@ -253,7 +256,7 @@ async def _get_collection_keys(self, *, collection: str, limit: int | None = Non
         if not (hits := get_hits_from_response(response=result)):
             return []
 
-        all_keys: list[str] = []
+        all_keys: Sequence[str] = []
 
         for hit in hits:
             if not (key := get_first_value_from_field_in_hit(hit=hit, field="key", value_type=str)):

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

@@ -1,6 +1,9 @@
-from typing import Any, overload
+from typing import TYPE_CHECKING, Any, overload
 from urllib.parse import urlparse
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 from key_value.shared.type_checking.bear_spray import bear_spray
 from key_value.shared.utils.compound import compound_key, get_keys_from_compound_keys
 from key_value.shared.utils.managed_entry import ManagedEntry
@@ -128,7 +131,7 @@ async def _get_collection_keys(self, *, collection: str, limit: int | None = Non
 
         # redis.asyncio scan returns tuple(cursor, keys)
         _cursor: int
-        keys: list[str]
+        keys: Sequence[str]
         _cursor, keys = await self._client.scan(cursor=0, match=pattern, count=limit)  # pyright: ignore[reportUnknownMemberType, reportAny]
 
         return get_keys_from_compound_keys(compound_keys=keys, 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)