Make interface more generic

[strawgate]

See recommendation from #103 (comment)

[claude]

Claude finished @strawgate's task —— View job

---

Issue #116 Analysis Complete ✓

Recommendation

Switch key input parameters from list[str] to Sequence[str] for the four bulk operation methods in the AsyncKeyValueProtocol. This change follows the same Liskov Substitution Principle successfully applied in PR #103 for values (dict → Mapping) and completes the pattern of "accept generic, return concrete" across the entire API surface.

Methods to update:

• get_many(keys: list[str], ...) → get_many(keys: Sequence[str], ...)
• ttl_many(keys: list[str], ...) → ttl_many(keys: Sequence[str], ...)
• put_many(keys: list[str], ...) → put_many(keys: Sequence[str], ...)
• delete_many(keys: list[str], ...) → delete_many(keys: Sequence[str], ...)

Scope: This will require updates to ~38 files (same as PR #103):

• 2 protocol files
• 2 base store files
• ~30 wrapper files
• ~4 adapter files

Benefits:

1. ✅ API Consistency: Both keys AND values use abstract input types
2. ✅ Increased Flexibility: Users can pass tuples, frozen sets, or other sequence types
3. ✅ Backward Compatible: list[str] is a Sequence[str], so all existing code works
4. ✅ Type Safety: Communicates that methods don't mutate input keys
5. ✅ Python Best Practice: Standard pattern for accepting collections as inputs

Findings

Context from PR #103

PR #103 (merged on 2025-10-26) successfully refactored the interface from dict[str, Any] to Mapping[str, Any] for input parameters while keeping return types as dict[str, Any]. In the review comment from that PR, Claude recommended:

Consider a follow-up PR to change key input parameters from list[str] to Sequence[str] for consistency with the Mapping pattern.

This issue (#116) was created specifically to implement that recommendation.

Current State

The AsyncKeyValueProtocol currently uses:

• ✅ Values: Mapping[str, Any] for inputs, dict[str, Any] for outputs (PR refactor: switch input parameters from dict to Mapping #103)
• ❌ Keys: list[str] for both inputs and outputs

Key methods currently accepting list[str]:

• Line 60: get_many(keys: list[str], ...)
• Line 72: ttl_many(keys: list[str], ...)
• Line 87: put_many(keys: list[str], ...)
• Line 104: delete_many(keys: list[str], ...)

Key methods returning list[str]:

• Line 131: keys(...) -> list[str] ✅ Should remain concrete
• Line 143: collections(...) -> list[str] ✅ Should remain concrete

Internal Implementation Analysis

I searched the codebase for how keys are used internally:

BaseStore (key-value/key-value-aio/src/key_value/aio/stores/base.py):

async def get_many(self, keys: list[str], ...) -> list[dict[str, Any] | None]:
    entries = await self._get_managed_entries(keys=keys, collection=collection)

Wrappers (prefix_keys, encryption, logging, retry, etc.):

• All wrappers iterate over keys or create new lists from keys
• Example from prefix_keys wrapper:

  new_keys: list[str] = [self._prefix_key(key=key) for key in keys]

• ✅ List comprehensions work perfectly with Sequence[str] inputs

No blockers identified: All internal code iterates over keys, which works identically with Sequence[str].

Why Sequence, Not List?

Pros:

1. Consistent with the PR refactor: switch input parameters from dict to Mapping #103 pattern (Mapping for values, Sequence for keys)
2. Accepts tuples, lists, and other iterable sequences
3. No breaking changes (100% backward compatible)
4. Better type safety (signals immutability of input)
5. Matches put_many(values: Sequence[Mapping[str, Any]]) already in the interface

Cons:

1. Moderate scope (~38 files to update)
2. Some wrappers create list[str] from keys internally (no issue, just internal conversion)

Detailed Action Plan

This plan is designed for a junior developer to implement the recommendation step-by-step.

Phase 1: Update Protocol Definitions

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

1. Update the import statement (line 1) to ensure Sequence is imported:

   from collections.abc import Mapping, Sequence

2. Update four method signatures in AsyncKeyValueProtocol:

   • Line 60: Change async def get_many(self, keys: list[str], ...
     To: async def get_many(self, keys: Sequence[str], ...

   • Line 72: Change async def ttl_many(self, keys: list[str], ...
     To: async def ttl_many(self, keys: Sequence[str], ...

   • Line 87: Change async def put_many(self, keys: list[str], ...
     To: async def put_many(self, keys: Sequence[str], ...

   • Line 104: Change async def delete_many(self, keys: list[str], ...
     To: async def delete_many(self, keys: Sequence[str], ...

3. Do NOT change the return types for:

   • Line 131: keys(...) -> list[str] (keep as list)
   • Line 143: collections(...) -> list[str] (keep as list)

Phase 2: Update Base Store Implementation

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

1. Update import to include Sequence:

   from collections.abc import Mapping, Sequence

2. Update method signatures (lines 140, 160, 226, 271):

   • async def get_many(self, keys: Sequence[str], ...
   • async def ttl_many(self, keys: Sequence[str], ...
   • async def put_many(self, keys: Sequence[str], ...
   • async def delete_many(self, keys: Sequence[str], ...

3. Update internal helper methods that accept keys:

   • Search for _get_managed_entries, _put_managed_entries, _delete_managed_entries
   • Update their signatures to accept Sequence[str] instead of list[str]

Phase 3: Update All Wrappers

Files: All files in key-value/key-value-aio/src/key_value/aio/wrappers/*/

For each wrapper file (34 files total):

1. Add Sequence to imports if not already present
2. Update the four bulk operation method signatures:
   • get_many(self, keys: Sequence[str], ...
   • ttl_many(self, keys: Sequence[str], ...
   • put_many(self, keys: Sequence[str], ...
   • delete_many(self, keys: Sequence[str], ...

Wrapper files to update:

• compression/wrapper.py
• encryption/base.py
• fallback/wrapper.py
• limit_size/wrapper.py
• logging/wrapper.py
• passthrough_cache/wrapper.py
• prefix_collections/wrapper.py
• prefix_keys/wrapper.py
• read_only/wrapper.py
• retry/wrapper.py
• statistics/wrapper.py
• timeout/wrapper.py
• ttl_clamp/wrapper.py
• And all others in the wrappers directory

Phase 4: Update Adapters

Files: Files in key-value/key-value-aio/src/key_value/aio/adapters/*/

Update adapter implementations that implement the protocol:

• pydantic/adapter.py
• raise_on_missing/adapter.py
• Any other adapters that implement bulk operations

Phase 5: Regenerate Sync Library

Command:

make sync

This will automatically update all corresponding files in key-value/key-value-sync/ to match the async changes.

Phase 6: Type Checking

Command:

make typecheck

Ensure all type checking passes with basedpyright in strict mode.

Phase 7: Run Tests

Command:

make test

Verify that all tests pass. No test changes should be required since list[str] is a valid Sequence[str].

Phase 8: Linting

Command:

make lint

Ensure all linting passes with Ruff.

Phase 9: Git Commit

git add .
git commit -m "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
- Regenerated sync library

Fixes #116

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

Co-Authored-By: Claude <noreply@anthropic.com>"

Expected Outcomes

• ✅ ~38 files updated with consistent Sequence[str] for key inputs
• ✅ All type checking passes (basedpyright strict mode)
• ✅ All tests pass (no test changes required)
• ✅ 100% backward compatible
• ✅ Sync library automatically regenerated

Related Items

Related Pull Requests

Repository	PR	Relevance
strawgate/py-key-value	PR #103: refactor: switch input parameters from dict to Mapping	Directly related - This PR implemented the Mapping change for values and recommended this follow-up change for keys in the review. Issue #116 was created from that recommendation.

Related Issues

Repository	Issue	Relevance
strawgate/py-key-value	Issue #94: Switch interface to mapping from dict	Related - Original issue that led to PR #103. This issue (#116) is the natural follow-up to complete the generic types pattern.

Related Files

Repository	File	Relevance	Key Lines
strawgate/py-key-value	key_value/aio/protocols/key_value.py	Primary file - Contains the protocol definition with the four bulk operation methods that need updating	60, 72, 87, 104
strawgate/py-key-value	key_value/aio/stores/base.py	Base implementation - BaseStore implementation that all stores inherit from	140, 160, 226, 271
strawgate/py-key-value	key_value/aio/wrappers/prefix_keys/wrapper.py	Example wrapper - Shows how wrappers create new lists from keys, which works fine with Sequence input	37-39

Related Webpages

Name	URL	Relevance
Python collections.abc Documentation	https://docs.python.org/3/library/collections.abc.html	Official Python documentation for abstract base classes including Sequence and Mapping
Liskov Substitution Principle	https://en.wikipedia.org/wiki/Liskov_substitution_principle	Design principle that guides this refactoring: accept more general types as inputs, return more specific types
Python Type Hints: Sequence vs List	https://mypy.readthedocs.io/en/stable/builtin_types.html#sequence-types	MyPy documentation explaining when to use Sequence vs list in type hints

---

[strawgate]

@claude please make a pull request

[claude]

Claude finished @strawgate's task —— View job • claude/issue-116-20251026-0416 • Create PR ➔

---

Implementation Complete ✓

Successfully switched key input parameters from list[str] to Sequence[str] for all bulk operation methods in the AsyncKeyValueProtocol. This change follows the Liskov Substitution Principle and completes the pattern started in PR #103.

Changes Made

• Updated protocol definitions (AsyncKeyValueProtocol)
• Updated base store implementation (BaseStore)
• Updated all 13 wrappers
• Updated 2 adapters (Pydantic, RaiseOnMissing)
• Updated shared utility functions (compound.py)
• Regenerated sync library automatically
• All type checks pass (basedpyright strict mode)
• All tests pass (87 passed)
• All linting passes (Ruff)

Summary

Methods updated (4):

• get_many(keys: Sequence[str], ...)
• ttl_many(keys: Sequence[str], ...)
• put_many(keys: Sequence[str], ...)
• delete_many(keys: Sequence[str], ...)

Files modified: 23 async files + auto-generated sync equivalents

Benefits:

• ✅ API Consistency - both keys AND values now use abstract input types
• ✅ Increased Flexibility - users can pass tuples, lists, or other sequences
• ✅ 100% Backward Compatible - list[str] is a Sequence[str]
• ✅ Type Safety - communicates that methods don't mutate input keys

---

|