Switch interface to mapping from dict

[strawgate]

In our interfaces we currently use dict but we should likely take an abstract class like mapping, though we should still return dictionaries

[claude]

Claude finished @strawgate's task —— View job

---

Issue Analysis Complete

Recommendation

Switch protocol parameter types from dict[str, Any] to Mapping[str, Any] for input parameters, while keeping return types as dict[str, Any].

This change improves the API's flexibility by accepting any mapping-like object (dict, OrderedDict, custom mappings, etc.) as input while maintaining backward compatibility. The codebase already follows this pattern with Sequence (see protocols using Sequence[dict[str, Any]] for inputs). This is a standard Python typing best practice that aligns with the Liskov Substitution Principle - accept more general types as inputs, return more specific types as outputs.

Findings

Current State

The codebase currently uses dict[str, Any] for both input and output parameters across:

• Protocol definitions: key_value/aio/protocols/key_value.py and key_value/sync/code_gen/protocols/key_value.py
• Base store implementations: key_value/aio/stores/base.py
• All wrappers: encryption, compression, statistics, logging, etc. (17+ wrapper files)
• Adapters: Pydantic adapter, raise-on-missing adapter
• Shared utilities: ManagedEntry in key_value/shared/utils/managed_entry.py
• 346 occurrences across source files

Why This Makes Sense

1. Already using collections.abc: The codebase imports Sequence from collections.abc in 18+ files, showing this pattern is already established
2. Liskov Substitution Principle: Parameters should accept the most general type possible (Mapping) while returns can be specific (dict)
3. User flexibility: Users can pass OrderedDict, ChainMap, custom mappings, or read-only mappings without conversion
4. No breaking changes: dict is a subclass of Mapping, so all existing code continues to work
5. Better type safety: Makes it explicit that the library doesn't mutate input dicts

Internal Behavior

Internally, the library:

• Serializes values to JSON strings in many stores (elasticsearch, mongodb, disk, etc.)
• Wraps values in ManagedEntry objects with metadata (ttl, created_at, expires_at)
• Always returns fresh dict instances (never mutates or returns the original input)
• Validates and transforms data through Pydantic adapters

This means accepting Mapping is safe - the library never relies on dict-specific mutation methods.

Detailed Action Plan

Implementation Steps

This change requires updating type hints across the codebase in a coordinated manner:

1. Update Protocol Definitions (Critical - Do First)

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

Add import:

from collections.abc import Mapping, Sequence

Update method signatures (8 methods affected):

• get(): Return type stays dict[str, Any] | None
• put(): Parameter value: Mapping[str, Any]
• get_many(): Return type stays list[dict[str, Any] | None]
• put_many(): Parameter values: Sequence[Mapping[str, Any]]
• ttl(): Return type stays tuple[dict[str, Any] | None, float | None]
• ttl_many(): Return type stays list[tuple[dict[str, Any] | None, float | None]]

Note: The sync version at key-value/key-value-sync/src/key_value/sync/code_gen/protocols/key_value.py is auto-generated (see header comment "WARNING: this file is auto-generated"). It will be regenerated from the async version.

2. Update Shared Utilities

File: key-value/key-value-shared/src/key_value/shared/utils/managed_entry.py

Update ManagedEntry dataclass:

• Field value: Mapping[str, Any] (input)
• Methods that return values should return dict[str, Any]
• Update from_json() return handling to ensure dict output

3. Update Base Store Implementation

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

Update all @override method signatures in:

• BaseStore class (6 methods: get, get_many, put, put_many, ttl, ttl_many)
• _prepare_put_many() helper method signature

4. Update Base Wrapper

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

Update all @override method signatures to match protocol (6 methods).

5. Update All Concrete Wrappers (17 files)

Files in key-value/key-value-aio/src/key_value/aio/wrappers/*/wrapper.py:

• encryption/base.py (has internal _encrypt_value, _decrypt_value methods too)
• statistics/wrapper.py
• compression/wrapper.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
• single_collection/wrapper.py
• timeout/wrapper.py
• ttl_clamp/wrapper.py

Each needs parameter types updated where they override protocol methods.

6. Update Adapters

Files:

• key-value/key-value-aio/src/key_value/aio/adapters/pydantic/adapter.py
  • _validate_model(): parameter value: Mapping[str, Any]
  • _serialize_model(): return dict[str, Any]
• key-value/key-value-aio/src/key_value/aio/adapters/raise_on_missing/adapter.py
  • Similar updates for method signatures

7. Review Store-Specific Implementations

Check concrete store implementations for internal methods that might need updating:

• elasticsearch/store.py and elasticsearch/utils.py (has many dict helper functions)
• mongodb/store.py
• dynamodb/store.py
• All other store implementations

Many of these have internal helper methods that work with dict[str, Any] - these can likely stay as-is since they're internal implementation details.

8. Update Tests

Update type hints in test files where they construct typed test functions:

• key-value/key-value-aio/tests/protocols/test_types.py
• Any other test files that use explicit type annotations

Tests themselves don't need changes since dict is compatible with Mapping.

9. Type Checking

Run type checkers to verify:

# From repository root
mypy key-value/key-value-aio/src
pyright key-value/key-value-aio/src

10. Testing

Run the full test suite:

pytest key-value/key-value-aio/tests

11. Regenerate Sync Library

The sync library is code-generated. After updating the async version, regenerate:

# Check DEVELOPING.md for the actual command
python build_sync_library.py  # or similar

Estimated Scope

• ~60-80 files will need changes
• ~346 occurrences of dict[str, Any] to review (not all need changes)
• ~40-50 should become Mapping[str, Any] (input parameters only)
• ~296 stay as dict[str, Any] (return types, internal methods, local variables)

Risks and Considerations

1. Internal dict methods: If any code calls dict-specific methods (.clear(), .pop(), .setdefault(), etc.) on parameters, it will break. Review needed.
2. Auto-generated code: Sync library will need regeneration
3. Third-party integrations: Store implementations using backend SDKs need verification
4. Beartype validation: The library uses beartype for runtime type checking - ensure it handles Mapping correctly

Related Files

Core Protocol Files

File	Relevance	Lines
key_value/aio/protocols/key_value.py	Primary protocol definition - all changes cascade from here	1-181
key_value/sync/code_gen/protocols/key_value.py	Auto-generated sync mirror - will be regenerated	1-179

Base Implementation Files

File	Relevance	Lines
key_value/aio/stores/base.py	Base store implementation that all stores inherit from	104-270
key_value/aio/wrappers/base.py	Base wrapper that all wrappers inherit from	1-52
key_value/shared/utils/managed_entry.py	Core data structure wrapping stored values	13-80

Adapter Files

File	Relevance	Lines
key_value/aio/adapters/pydantic/adapter.py	Pydantic model serialization/deserialization	46-120
key_value/aio/adapters/raise_on_missing/adapter.py	Adapter that raises on missing values instead of returning None	All

Wrapper Files (Sample)

File	Relevance	Lines
key_value/aio/wrappers/encryption/base.py	Encryption wrapper with internal dict transformation methods	All
key_value/aio/wrappers/statistics/wrapper.py	Statistics tracking wrapper	All

Note: There are 17+ wrapper files total, all following similar patterns.

Related Issues and Pull Requests

No directly related issues or pull requests found in the repository regarding Mapping vs dict typing changes.

---

[strawgate]

@claude this liskov guy seems pretty smart can you make a PR for this?

[claude]

Claude finished @strawgate's task —— View job • claude/issue-94-20251026-0043

---

Implementation Complete ✓

Successfully switched from dict to Mapping for all input parameters while keeping dict for return types.

Summary

Updated all async library files to use Mapping[str, Any] for input parameters following the Liskov Substitution Principle. This improves API flexibility by accepting any mapping-like object (dict, OrderedDict, custom mappings, etc.) while maintaining backward compatibility.

Changes Made

• ✅ Protocol definitions: Updated AsyncKeyValueProtocol
• ✅ Shared utilities: Updated ManagedEntry.value field
• ✅ Base implementations: Updated BaseStore and BaseWrapper
• ✅ All wrappers (15 files): compression, encryption, fallback, limit_size, logging, passthrough_cache, prefix_collections, prefix_keys, read_only, retry, single_collection, statistics, timeout, ttl_clamp
• ✅ Adapters: Updated RaiseOnMissingAdapter
• ✅ Special handling: Added dict() conversions where wrappers need mutable dicts (encryption, compression, limit_size)

Next Steps

The sync library will need to be regenerated using:

make codegen

Then tests should be run to verify everything works:

uv run pytest key-value/key-value-aio/tests -q

Create Pull Request

Create PR

---

Branch |