refactor: switch input parameters from dict to Mapping

Switch all input parameters from `dict[str, Any]` to `Mapping[str, Any]` while keeping return types as `dict[str, Any]`. This follows the Liskov Substitution Principle - accept more general types as inputs, return more specific types as outputs.

This change improves the API's flexibility by accepting any mapping-like object (dict, OrderedDict, custom mappings, etc.) as input while maintaining backward compatibility. All existing code continues to work since dict is a subclass of Mapping.

Changes:
- Updated AsyncKeyValueProtocol with Mapping for put() and put_many() parameters
- Updated ManagedEntry.value field to accept Mapping[str, Any]
- Updated BaseStore and all wrapper implementations
- Updated adapters (RaiseOnMissingAdapter)
- Added dict() conversions where needed (encryption, compression, limit_size wrappers)

Note: Sync library will need to be regenerated from the async version.

Fixes #94

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

Co-Authored-By: William Easton <strawgate@users.noreply.github.com>

Author: github-actions[bot]

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

@@ -1,4 +1,4 @@
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import Any, Literal, SupportsFloat, overload
 
 from key_value.shared.errors import MissingKeyError
@@ -138,7 +138,7 @@ async def ttl_many(
 
         return results
 
-    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         """Store a key-value pair in the specified collection with optional TTL.
 
         Args:
@@ -153,7 +153,7 @@ async def put(self, key: str, value: dict[str, Any], *, collection: str | None =
     async def put_many(
         self,
         keys: list[str],
-        values: Sequence[dict[str, Any]],
+        values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
         ttl: Sequence[SupportsFloat | None] | None = None,

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

@@ -1,4 +1,4 @@
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import Any, Protocol, SupportsFloat, runtime_checkable
 
 
@@ -36,7 +36,7 @@ async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[st
         """
         ...
 
-    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         """Store a key-value pair in the specified collection with optional TTL.
 
         Args:
@@ -85,7 +85,7 @@ async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> l
     async def put_many(
         self,
         keys: list[str],
-        values: Sequence[dict[str, Any]],
+        values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
         ttl: Sequence[SupportsFloat | None] | None = None,

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

@@ -5,7 +5,7 @@
 from abc import ABC, abstractmethod
 from asyncio.locks import Lock
 from collections import defaultdict
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from types import TracebackType
 from typing import Any, SupportsFloat
 
@@ -190,7 +190,7 @@ async def _put_managed_entries(self, *, collection: str, keys: list[str], manage
             )
 
     @override
-    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         """Store a key-value pair in the specified collection with optional TTL."""
         collection = collection or self.default_collection
         await self.setup_collection(collection=collection)
@@ -204,8 +204,8 @@ async def put(self, key: str, value: dict[str, Any], *, collection: str | None =
         )
 
     def _prepare_put_many(
-        self, *, keys: list[str], values: Sequence[dict[str, Any]], ttl: Sequence[SupportsFloat | None] | SupportsFloat | None
-    ) -> tuple[list[str], Sequence[dict[str, Any]], list[float | None]]:
+        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]]:
         """Prepare multiple managed entries for a put_many operation.
 
         Inheriting classes can use this method if they need to modify a put_many operation."""
@@ -226,7 +226,7 @@ def _prepare_put_many(
     async def put_many(
         self,
         keys: list[str],
-        values: Sequence[dict[str, Any]],
+        values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
         ttl: Sequence[SupportsFloat | None] | None = None,

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

@@ -1,4 +1,4 @@
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import Any, SupportsFloat
 
 from typing_extensions import override
@@ -28,14 +28,14 @@ async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> l
         return await self.key_value.ttl_many(collection=collection, keys=keys)
 
     @override
-    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         return await self.key_value.put(collection=collection, key=key, value=value, ttl=ttl)
 
     @override
     async def put_many(
         self,
         keys: list[str],
-        values: Sequence[dict[str, Any]],
+        values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
         ttl: Sequence[SupportsFloat | None] | None = None,

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

@@ -1,7 +1,7 @@
 import base64
 import gzip
 import json
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import Any, SupportsFloat
 
 from key_value.shared.utils.managed_entry import ManagedEntry
@@ -131,18 +131,18 @@ async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> l
         return [(self._decompress_value(value), ttl) for value, ttl in results]
 
     @override
-    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
-        compressed_value = self._compress_value(value)
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+        compressed_value = self._compress_value(dict(value))
         return await self.key_value.put(key=key, value=compressed_value, collection=collection, ttl=ttl)
 
     @override
     async def put_many(
         self,
         keys: list[str],
-        values: Sequence[dict[str, Any]],
+        values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
         ttl: Sequence[SupportsFloat | None] | None = None,
     ) -> None:
-        compressed_values = [self._compress_value(value) for value in values]
+        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)

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

@@ -1,6 +1,6 @@
 import base64
 import json
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from typing import Any, SupportsFloat
 
 from key_value.shared.errors.key_value import SerializationError
@@ -158,18 +158,18 @@ async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> l
         return [(self._decrypt_value(value), ttl) for value, ttl in results]
 
     @override
-    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
-        encrypted_value = self._encrypt_value(value)
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+        encrypted_value = self._encrypt_value(dict(value))
         return await self.key_value.put(key=key, value=encrypted_value, collection=collection, ttl=ttl)
 
     @override
     async def put_many(
         self,
         keys: list[str],
-        values: Sequence[dict[str, Any]],
+        values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
         ttl: Sequence[SupportsFloat | None] | None = None,
     ) -> None:
-        encrypted_values = [self._encrypt_value(value) for value in values]
+        encrypted_values = [self._encrypt_value(dict(value)) for value in values]
         return await self.key_value.put_many(keys=keys, values=encrypted_values, collection=collection, ttl=ttl)

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

@@ -1,4 +1,4 @@
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import Any, SupportsFloat
 
 from typing_extensions import override
@@ -71,7 +71,7 @@ async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> l
             return await self.fallback_key_value.ttl_many(keys=keys, collection=collection)
 
     @override
-    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         if self.write_to_fallback:
             try:
                 return await self.primary_key_value.put(key=key, value=value, collection=collection, ttl=ttl)
@@ -84,7 +84,7 @@ async def put(self, key: str, value: dict[str, Any], *, collection: str | None =
     async def put_many(
         self,
         keys: list[str],
-        values: Sequence[dict[str, Any]],
+        values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
         ttl: Sequence[SupportsFloat | None] | None = None,

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

@@ -1,4 +1,4 @@
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import Any, SupportsFloat
 
 from key_value.shared.errors.wrappers.limit_size import EntryTooLargeError, EntryTooSmallError
@@ -80,28 +80,28 @@ def _within_size_limit(self, value: dict[str, Any], *, collection: str | None =
         return True
 
     @override
-    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
-        if self._within_size_limit(value=value, collection=collection, key=key):
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+        if self._within_size_limit(value=dict(value), collection=collection, key=key):
             await self.key_value.put(collection=collection, key=key, value=value, ttl=ttl)
 
     @override
     async def put_many(
         self,
         keys: list[str],
-        values: Sequence[dict[str, Any]],
+        values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
         ttl: Sequence[SupportsFloat | None] | None = None,
     ) -> None:
         filtered_keys: list[str] = []
-        filtered_values: list[dict[str, Any]] = []
+        filtered_values: list[Mapping[str, Any]] = []
         filtered_ttls: list[SupportsFloat | None] | None = None
 
         if isinstance(ttl, Sequence):
             filtered_ttls = []
 
         for i, (k, v) in enumerate(zip(keys, values, strict=True)):
-            if self._within_size_limit(value=v, collection=collection, key=k):
+            if self._within_size_limit(value=dict(v), collection=collection, key=k):
                 filtered_keys.append(k)
                 filtered_values.append(v)
                 if isinstance(ttl, Sequence):

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

@@ -1,6 +1,6 @@
 import json
 import logging
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import Any, Literal, SupportsFloat
 
 from typing_extensions import override
@@ -146,7 +146,7 @@ async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> l
         return results
 
     @override
-    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         self._log(state="start", action="PUT", keys=key, collection=collection, values=value, extra={"ttl": ttl})
 
         await self.key_value.put(key=key, value=value, collection=collection, ttl=ttl)
@@ -157,7 +157,7 @@ async def put(self, key: str, value: dict[str, Any], *, collection: str | None =
     async def put_many(
         self,
         keys: list[str],
-        values: Sequence[dict[str, Any]],
+        values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
         ttl: Sequence[SupportsFloat | None] | None = None,

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

@@ -1,4 +1,4 @@
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import Any, SupportsFloat
 
 from typing_extensions import override
@@ -155,7 +155,7 @@ async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> l
         return [key_to_value[key] for key in keys]
 
     @override
-    async def put(self, key: str, value: dict[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         _ = await self.cache_key_value.delete(collection=collection, key=key)
 
         await self.primary_key_value.put(collection=collection, key=key, value=value, ttl=ttl)
@@ -164,7 +164,7 @@ async def put(self, key: str, value: dict[str, Any], *, collection: str | None =
     async def put_many(
         self,
         keys: list[str],
-        values: Sequence[dict[str, Any]],
+        values: Sequence[Mapping[str, Any]],
         *,
         collection: str | None = None,
         ttl: Sequence[SupportsFloat | None] | None = None,