refactor: switch input parameters from dict to Mapping (#103)

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

Author: strawgate

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
 
@@ -134,15 +134,15 @@ async def get(
         if managed_entry.is_expired:
             return None
 
-        return managed_entry.value
+        return dict(managed_entry.value)
 
     @override
     async def get_many(self, keys: list[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
         collection = collection or self.default_collection
         await self.setup_collection(collection=collection)
 
         entries = await self._get_managed_entries(keys=keys, collection=collection)
-        return [entry.value if entry and not entry.is_expired else None for entry in entries]
+        return [dict(entry.value) if entry and not entry.is_expired else None for entry in entries]
 
     @override
     async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[str, Any] | None, float | None]:
@@ -154,7 +154,7 @@ async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[st
         if not managed_entry or managed_entry.is_expired:
             return (None, None)
 
-        return (managed_entry.value, managed_entry.ttl)
+        return (dict(managed_entry.value), managed_entry.ttl)
 
     @override
     async def ttl_many(
@@ -172,7 +172,7 @@ async def ttl_many(
         await self.setup_collection(collection=collection)
 
         entries = await self._get_managed_entries(keys=keys, collection=collection)
-        return [(entry.value, entry.ttl) if entry and not entry.is_expired else (None, None) for entry in entries]
+        return [(dict(entry.value), entry.ttl) if entry and not entry.is_expired else (None, None) for entry in entries]
 
     @abstractmethod
     async def _put_managed_entry(self, *, collection: str, key: str, managed_entry: ManagedEntry) -> None:
@@ -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
@@ -59,7 +59,7 @@ def _format_message(
         action: str,
         keys: list[str] | str,
         collection: str | None,
-        values: dict[str, Any] | Sequence[dict[str, Any]] | None = None,
+        values: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None = None,
         extra: dict[str, Any] | None = None,
     ) -> str:
         if self.structured_logs:
@@ -92,7 +92,7 @@ def _log(
         action: str,
         keys: list[str] | str,
         collection: str | None,
-        values: dict[str, Any] | Sequence[dict[str, Any]] | None = None,
+        values: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None = None,
         extra: dict[str, Any] | None = None,
     ) -> None:
         self.logger.log(
@@ -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,