Merge branch 'main' into claude/issue-115-20251026-0511

Author: strawgate

.devcontainer/devcontainer.json

@@ -0,0 +1,39 @@
+{
+  "name": "py-key-value",
+  "image": "ghcr.io/astral-sh/uv:python3.10-bookworm",
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "lts"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers/features/git:1": {}
+  },
+  "runArgs": [
+    "--network=host"
+  ],
+  "mounts": [
+    "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
+  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "charliermarsh.ruff",
+        "DavidAnson.vscode-markdownlint"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/usr/local/bin/python",
+        "python.testing.pytestEnabled": true,
+        "python.testing.unittestEnabled": false,
+        "python.testing.pytestArgs": [
+          "key-value",
+          "--import-mode=importlib",
+          "-vv"
+        ]
+      }
+    }
+  },
+  "postCreateCommand": "make sync",
+  "remoteUser": "root"
+}

.gitignore

@@ -6,6 +6,9 @@ __pycache__/
 # C extensions
 *.so
 
+# MacOS junk
+.DS_Store
+
 # Distribution / packaging
 .Python
 build/

AGENTS.md

@@ -106,7 +106,10 @@ pip install py-key-value-aio[mongodb]    # MongoDB support
 
 **Never edit files in `key-value/key-value-sync/` directly**. Any changes
 will be overwritten when `make codegen` runs. Always make changes in the
-async package and regenerate.
+async package and regenerate. Always run `make codegen` after making changes
+to the async package. You will need to include the generated code in your pull
+request. Nobody will generate it for you. This also means pull requests will contain
+two copies of your changes, this is intentional!
 
 ## Make Commands Reference
 

Makefile

@@ -75,7 +75,7 @@ ifdef PROJECT
 	@cd $(PROJECT) && uv sync --locked --group dev
 else
 	@echo "Syncing all packages..."
-	@uv sync --all-packages
+	@uv sync --all-packages --group dev
 	@npm install -g markdownlint-cli
 endif
 

README.md

@@ -296,6 +296,7 @@ The following wrappers are available:
 
 | Wrapper | Description | Example |
 |---------|---------------|-----|
+| CollectionRoutingWrapper | Route operations to different stores based on a collection name. | `CollectionRoutingWrapper(collection_map={"sessions": redis_store, "users": dynamo_store}, default_store=memory_store)` |
 | CompressionWrapper | Compress values before storing and decompress on retrieval. | `CompressionWrapper(key_value=memory_store, min_size_to_compress=0)` |
 | FernetEncryptionWrapper | Encrypt values before storing and decrypt on retrieval. | `FernetEncryptionWrapper(key_value=memory_store, source_material="your-source-material", salt="your-salt")` |
 | FallbackWrapper | Fallback to a secondary store when the primary store fails. | `FallbackWrapper(primary_key_value=memory_store, fallback_key_value=memory_store)` |
@@ -306,6 +307,7 @@ The following wrappers are available:
 | PrefixKeysWrapper | Prefix all keys with a given prefix. | `PrefixKeysWrapper(key_value=memory_store, prefix="users")` |
 | ReadOnlyWrapper | Prevent all write operations on the underlying store. | `ReadOnlyWrapper(key_value=memory_store, raise_on_write=True)` |
 | RetryWrapper | Retry failed operations with exponential backoff. | `RetryWrapper(key_value=memory_store, max_retries=3, initial_delay=0.1, max_delay=10.0, exponential_base=2.0)` |
+| RoutingWrapper | Route operations to different stores based on a routing function. | `RoutingWrapper(routing_function=lambda collection: redis_store if collection == "sessions" else dynamo_store, default_store=memory_store)` |
 | SingleCollectionWrapper | Wrap a store to only use a single collection. | `SingleCollectionWrapper(key_value=memory_store, single_collection="users")` |
 | TTLClampWrapper | Clamp the TTL to a given range. | `TTLClampWrapper(key_value=memory_store, min_ttl=60, max_ttl=3600)` |
 | StatisticsWrapper | Track operation statistics for the store. | `StatisticsWrapper(key_value=memory_store)` |

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

@@ -15,6 +15,12 @@
 class PydanticAdapter(Generic[T]):
     """Adapter around a KVStore-compliant Store that allows type-safe persistence of Pydantic models."""
 
+    _key_value: AsyncKeyValue
+    _is_list_model: bool
+    _type_adapter: TypeAdapter[T]
+    _default_collection: str | None
+    _raise_on_validation_error: bool
+
     # Beartype doesn't like our `type[T] includes a bound on Sequence[...] as the subscript is not checkable at runtime
     # For just the next 20 or so lines we are no longer bear bros but have no fear, we will be back soon!
     @bear_spray
@@ -34,14 +40,14 @@ def __init__(
             raise_on_validation_error: Whether to raise a ValidationError if the model is invalid.
         """
 
-        self._key_value: AsyncKeyValue = key_value
+        self._key_value = key_value
 
         origin = get_origin(pydantic_model)
-        self._is_list_model: bool = origin is not None and issubclass(origin, Sequence)
+        self._is_list_model = origin is not None and isinstance(origin, type) and issubclass(origin, Sequence)
 
         self._type_adapter = TypeAdapter[T](pydantic_model)
-        self._default_collection: str | None = default_collection
-        self._raise_on_validation_error: bool = raise_on_validation_error
+        self._default_collection = default_collection
+        self._raise_on_validation_error = raise_on_validation_error
 
     def _validate_model(self, value: dict[str, Any]) -> T | None:
         try:
@@ -60,7 +66,7 @@ def _serialize_model(self, value: T) -> dict[str, Any]:
             if self._is_list_model:
                 return {"items": self._type_adapter.dump_python(value, mode="json")}
 
-            return self._type_adapter.dump_python(value, mode="json")
+            return self._type_adapter.dump_python(value, mode="json")  # pyright: ignore[reportAny]
         except PydanticSerializationError as e:
             msg = f"Invalid Pydantic model: {e}"
             raise SerializationError(msg) from e

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

@@ -71,7 +71,7 @@ def __init__(self, *, default_collection: str | None = None) -> None:
     async def _setup(self) -> None:
         """Initialize the store (called once before first use)."""
 
-    async def _setup_collection(self, *, collection: str) -> None:  # pyright: ignore[reportUnusedParameter]
+    async def _setup_collection(self, *, collection: str) -> None:
         """Initialize the collection (called once before first use of the collection)."""
 
     async def setup(self) -> None:

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

@@ -85,7 +85,7 @@ async def _get_managed_entry(self, *, key: str, collection: str) -> ManagedEntry
 
         expire_epoch: float | None
 
-        managed_entry_str, expire_epoch = self._cache.get(key=combo_key, expire_time=True)  # pyright: ignore[reportAny]
+        managed_entry_str, expire_epoch = self._cache.get(key=combo_key, expire_time=True)
 
         if not isinstance(managed_entry_str, str):
             return None

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

@@ -101,7 +101,7 @@ def __init__(
         if client:
             self._client = client
         else:
-            session: Session = aioboto3.Session(  # pyright: ignore[reportAny]
+            session: Session = aioboto3.Session(
                 region_name=region_name,
                 aws_access_key_id=aws_access_key_id,
                 aws_secret_access_key=aws_secret_access_key,

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

@@ -44,7 +44,7 @@ def to_managed_entry(self) -> ManagedEntry:
         return ManagedEntry.from_json(json_str=self.json_str)
 
 
-def _memory_cache_ttu(_key: Any, value: MemoryCacheEntry, now: float) -> float:  # pyright: ignore[reportAny]
+def _memory_cache_ttu(_key: Any, value: MemoryCacheEntry, now: float) -> float:
     """Calculate time-to-use for cache entries based on their TTL."""
     if value.ttl_at_insert is None:
         return float(sys.maxsize)
@@ -56,7 +56,7 @@ def _memory_cache_ttu(_key: Any, value: MemoryCacheEntry, now: float) -> float:
     return float(expiration_epoch)
 
 
-def _memory_cache_getsizeof(value: MemoryCacheEntry) -> int:  # pyright: ignore[reportUnusedParameter]
+def _memory_cache_getsizeof(value: MemoryCacheEntry) -> int:  # noqa: ARG001
     """Return size of cache entry (always 1 for entry counting)."""
     return 1