Merge branch 'main' into claude/issue-11-20251026-2132

Author: strawgate

.github/workflows/claude-on-test-failure.yml

@@ -138,7 +138,7 @@ jobs:
                   "github-research-mcp"
                 ],
                 "env": {
-                  "DISABLE_SUMMARIES": "true",  # Disable verbose summaries for faster analysis
+                  "DISABLE_SUMMARIES": "true",
                   "GITHUB_PERSONAL_ACCESS_TOKEN": "${{ secrets.GITHUB_TOKEN }}"
                 }
               }

docs/api/index.md

@@ -0,0 +1,58 @@
+# API Reference
+
+Complete API reference documentation for py-key-value.
+
+## Overview
+
+The py-key-value API is organized into four main components:
+
+- **[Protocols](protocols.md)** - Core interfaces for the key-value store
+- **[Stores](stores.md)** - Backend implementations for different storage systems
+- **[Wrappers](wrappers.md)** - Decorators that add functionality to stores
+- **[Adapters](adapters.md)** - Utilities that simplify working with stores
+
+## Quick Links
+
+### Core Protocols
+
+The [`AsyncKeyValue`](protocols.md) protocol defines the async interface that all
+stores implement.
+
+The [`KeyValue`](protocols.md) protocol is the synchronous version.
+
+### Popular Stores
+
+- [MemoryStore](stores.md) - In-memory storage
+- [RedisStore](stores.md) - Redis backend
+- [DiskStore](stores.md) - File-based storage
+
+### Common Wrappers
+
+- [LoggingWrapper](wrappers.md) - Add logging to any store
+- [CacheWrapper](wrappers.md) - Add caching layer
+- [RetryWrapper](wrappers.md) - Add automatic retry logic
+
+## Using the API Reference
+
+Each page provides:
+
+- **Type signatures** - Full type information for all parameters and return values
+- **Docstrings** - Detailed descriptions of functionality
+- **Source links** - View the implementation on GitHub
+- **Cross-references** - Navigate between related components
+
+## Example Usage
+
+```python
+from key_value.aio.stores.memory import MemoryStore
+from key_value.aio.wrappers.logging import LoggingWrapper
+
+# Create a store with logging
+store = LoggingWrapper(MemoryStore())
+
+# Use the store
+await store.put("key", "value")
+result = await store.get("key")
+```
+
+For more examples and guides, see the [User Guide](../stores.md).

key-value/key-value-aio/src/key_value/aio/stores/disk/multi_store.py

@@ -132,7 +132,11 @@ async def _put_managed_entry(
         collection: str,
         managed_entry: ManagedEntry,
     ) -> None:
-        _ = self._cache[collection].set(key=key, value=self._serialization_adapter.dump_json(entry=managed_entry), expire=managed_entry.ttl)
+        _ = self._cache[collection].set(
+            key=key,
+            value=self._serialization_adapter.dump_json(entry=managed_entry, key=key, collection=collection),
+            expire=managed_entry.ttl,
+        )
 
     @override
     async def _delete_managed_entry(self, *, key: str, collection: str) -> bool:

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

@@ -107,7 +107,11 @@ async def _put_managed_entry(
     ) -> None:
         combo_key: str = compound_key(collection=collection, key=key)
 
-        _ = self._cache.set(key=combo_key, value=self._serialization_adapter.dump_json(entry=managed_entry), expire=managed_entry.ttl)
+        _ = self._cache.set(
+            key=combo_key,
+            value=self._serialization_adapter.dump_json(entry=managed_entry, key=key, collection=collection),
+            expire=managed_entry.ttl,
+        )
 
     @override
     async def _delete_managed_entry(self, *, key: str, collection: str) -> bool:

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

@@ -219,7 +219,7 @@ async def _put_managed_entry(
         managed_entry: ManagedEntry,
     ) -> None:
         """Store a managed entry in DynamoDB."""
-        json_value = self._serialization_adapter.dump_json(entry=managed_entry)
+        json_value = self._serialization_adapter.dump_json(entry=managed_entry, key=key, collection=collection)
 
         item: dict[str, Any] = {
             "collection": {"S": collection},

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

@@ -67,6 +67,9 @@
         "key": {
             "type": "keyword",
         },
+        "version": {
+            "type": "integer",
+        },
         "value": {
             "properties": {
                 "flattened": {
@@ -357,7 +360,7 @@ async def _put_managed_entry(
         index_name: str = self._get_index_name(collection=collection)
         document_id: str = self._get_document_id(key=key)
 
-        document: dict[str, Any] = self._serializer.dump_dict(entry=managed_entry)
+        document: dict[str, Any] = self._serializer.dump_dict(entry=managed_entry, key=key, collection=collection)
 
         try:
             _ = await self._client.index(
@@ -395,7 +398,7 @@ async def _put_managed_entries(
 
             index_action: dict[str, Any] = new_bulk_action(action="index", index=index_name, document_id=document_id)
 
-            document: dict[str, Any] = self._serializer.dump_dict(entry=managed_entry)
+            document: dict[str, Any] = self._serializer.dump_dict(entry=managed_entry, key=key, collection=collection)
 
             operations.extend([index_action, document])
 

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

@@ -1,5 +1,8 @@
 """Python keyring-based key-value store."""
 
+import os
+
+from key_value.shared.errors.key_value import ValueTooLargeError
 from key_value.shared.utils.compound import compound_key
 from key_value.shared.utils.managed_entry import ManagedEntry
 from key_value.shared.utils.sanitization import HybridSanitizationStrategy, SanitizationStrategy
@@ -17,6 +20,16 @@
 
 DEFAULT_KEYCHAIN_SERVICE = "py-key-value"
 
+
+def is_value_too_large(value: bytes) -> bool:
+    value_length = len(value)
+    if os.name == "nt":
+        return value_length > WINDOWS_MAX_VALUE_LENGTH
+    return False
+
+
+WINDOWS_MAX_VALUE_LENGTH = 2560  # bytes
+
 MAX_KEY_COLLECTION_LENGTH = 256
 ALLOWED_KEY_COLLECTION_CHARACTERS: str = ALPHANUMERIC_CHARACTERS
 
@@ -105,7 +118,11 @@ async def _put_managed_entry(self, *, key: str, collection: str, managed_entry:
 
         combo_key: str = compound_key(collection=sanitized_collection, key=sanitized_key)
 
-        json_str: str = self._serialization_adapter.dump_json(entry=managed_entry)
+        json_str: str = self._serialization_adapter.dump_json(entry=managed_entry, key=key, collection=collection)
+        encoded_json_bytes: bytes = json_str.encode(encoding="utf-8")
+
+        if is_value_too_large(value=encoded_json_bytes):
+            raise ValueTooLargeError(size=len(encoded_json_bytes), max_size=2560, collection=sanitized_collection, key=sanitized_key)
 
         keyring.set_password(service_name=self._service_name, username=combo_key, password=json_str)
 

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

@@ -125,7 +125,7 @@ async def _put_managed_entry(
         else:
             exptime = max(int(managed_entry.ttl), 1)
 
-        json_value: str = self._serialization_adapter.dump_json(entry=managed_entry)
+        json_value: str = self._serialization_adapter.dump_json(entry=managed_entry, key=key, collection=collection)
 
         _ = await self._client.set(
             key=combo_key.encode(encoding="utf-8"),

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

@@ -219,7 +219,7 @@ async def _setup_collection(self, *, collection: str) -> None:
         # Ensure index on the unique combo key and supporting queries
         sanitized_collection = self._sanitize_collection(collection=collection)
 
-        collection_filter: dict[str, str] = {"name": collection}
+        collection_filter: dict[str, str] = {"name": sanitized_collection}
         matching_collections: list[str] = await self._db.list_collection_names(filter=collection_filter)
 
         if matching_collections:
@@ -273,7 +273,7 @@ async def _put_managed_entry(
         collection: str,
         managed_entry: ManagedEntry,
     ) -> None:
-        mongo_doc = self._adapter.dump_dict(entry=managed_entry)
+        mongo_doc = self._adapter.dump_dict(entry=managed_entry, key=key, collection=collection)
 
         try:
             # Ensure that the value is serializable to JSON
@@ -308,7 +308,7 @@ async def _put_managed_entries(
 
         operations: list[UpdateOne] = []
         for key, managed_entry in zip(keys, managed_entries, strict=True):
-            mongo_doc = self._adapter.dump_dict(entry=managed_entry)
+            mongo_doc = self._adapter.dump_dict(entry=managed_entry, key=key, collection=collection)
 
             operations.append(
                 UpdateOne(
@@ -346,8 +346,7 @@ async def _delete_collection(self, *, collection: str) -> bool:
 
         _ = await self._db.drop_collection(name_or_collection=collection_name)
 
-        if collection_name in self._collections_by_name:
-            del self._collections_by_name[collection]
+        self._collections_by_name.pop(collection, None)
 
         return True
 

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

@@ -132,7 +132,7 @@ async def _put_managed_entry(
     ) -> None:
         combo_key: str = compound_key(collection=collection, key=key)
 
-        json_value: str = self._adapter.dump_json(entry=managed_entry)
+        json_value: str = self._adapter.dump_json(entry=managed_entry, key=key, collection=collection)
 
         if managed_entry.ttl is not None:
             # Redis does not support <= 0 TTLs
@@ -160,7 +160,7 @@ async def _put_managed_entries(
             # If there is no TTL, we can just do a simple mset
             mapping: dict[str, str] = {}
             for key, managed_entry in zip(keys, managed_entries, strict=True):
-                json_value = self._adapter.dump_json(entry=managed_entry)
+                json_value = self._adapter.dump_json(entry=managed_entry, key=key, collection=collection)
                 mapping[compound_key(collection=collection, key=key)] = json_value
 
             await self._client.mset(mapping=mapping)
@@ -175,7 +175,7 @@ async def _put_managed_entries(
 
         for key, managed_entry in zip(keys, managed_entries, strict=True):
             combo_key: str = compound_key(collection=collection, key=key)
-            json_value = self._adapter.dump_json(entry=managed_entry)
+            json_value = self._adapter.dump_json(entry=managed_entry, key=key, collection=collection)
 
             pipeline.setex(name=combo_key, time=ttl_seconds, value=json_value)