Merge branch 'main' into claude/issue-87-20251027-0227

Author: strawgate

.github/workflows/claude-on-mention.yml

@@ -27,6 +27,11 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
       # Install UV package manager
       - name: Install UV
         uses: astral-sh/setup-uv@v7

.github/workflows/claude-on-open-label.yml

@@ -22,6 +22,11 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
       # Install UV package manager
       - name: Install UV
         uses: astral-sh/setup-uv@v7

key-value/key-value-sync/src/key_value/sync/code_gen/adapters/pydantic/adapter.py

@@ -50,6 +50,21 @@ def __init__(
         self._raise_on_validation_error = raise_on_validation_error
 
     def _validate_model(self, value: dict[str, Any]) -> T | None:
+        """Validate and deserialize a dict into the configured Pydantic model.
+
+        This method handles both single models and list models. For list models, it expects the value
+        to contain an "items" key with the list data, following the convention used by `_serialize_model`.
+        If validation fails and `raise_on_validation_error` is False, returns None instead of raising.
+
+        Args:
+            value: The dict to validate and convert to a Pydantic model.
+
+        Returns:
+            The validated model instance, or None if validation fails and errors are suppressed.
+
+        Raises:
+            DeserializationError: If validation fails and `raise_on_validation_error` is True.
+        """
         try:
             if self._is_list_model:
                 return self._type_adapter.validate_python(value.get("items", []))
@@ -62,6 +77,22 @@ def _validate_model(self, value: dict[str, Any]) -> T | None:
             return None
 
     def _serialize_model(self, value: T) -> dict[str, Any]:
+        """Serialize a Pydantic model to a dict for storage.
+
+        This method handles both single models and list models. For list models, it wraps the serialized
+        list in a dict with an "items" key (e.g., {"items": [...]}) to ensure consistent dict-based storage
+        format across all value types. This wrapping convention is expected by `_validate_model` during
+        deserialization.
+
+        Args:
+            value: The Pydantic model instance to serialize.
+
+        Returns:
+            A dict representation of the model suitable for storage.
+
+        Raises:
+            SerializationError: If the model cannot be serialized.
+        """
         try:
             if self._is_list_model:
                 return {"items": self._type_adapter.dump_python(value, mode="json")}
@@ -91,6 +122,10 @@ def get(self, key: str, *, collection: str | None = None, default: T | None = No
         Raises:
             DeserializationError if the stored data cannot be validated as the model and the PydanticAdapter is configured to
             raise on validation error.
+
+        Note:
+            When raise_on_validation_error=False and validation fails, returns the default value (which may be None).
+            When raise_on_validation_error=True and validation fails, raises DeserializationError.
         """
         collection = collection or self._default_collection
 
@@ -121,6 +156,11 @@ def get_many(self, keys: Sequence[str], *, collection: str | None = None, defaul
         Raises:
             DeserializationError if the stored data cannot be validated as the model and the PydanticAdapter is configured to
             raise on validation error.
+
+        Note:
+            When raise_on_validation_error=False and validation fails for any key, that position in the returned list
+            will contain the default value (which may be None). The method returns a complete list matching the order
+            and length of the input keys, with defaults substituted for missing or invalid entries.
         """
         collection = collection or self._default_collection
 
@@ -171,7 +211,16 @@ def delete_many(self, keys: Sequence[str], *, collection: str | None = None) ->
     def ttl(self, key: str, *, collection: str | None = None) -> tuple[T | None, float | None]:
         """Get a model and its TTL seconds if present.
 
-        Returns (model, ttl_seconds) or (None, None) if missing.
+        Args:
+            key: The key to retrieve.
+            collection: The collection to use. If not provided, uses the default collection.
+
+        Returns:
+            A tuple of (model, ttl_seconds). Returns (None, None) if the key is missing or validation fails.
+
+        Note:
+            When validation fails and raise_on_validation_error=False, returns (None, None) even if TTL data exists.
+            When validation fails and raise_on_validation_error=True, raises DeserializationError.
         """
         collection = collection or self._default_collection
 

key-value/key-value-sync/src/key_value/sync/code_gen/protocols/key_value.py

@@ -7,7 +7,12 @@
 
 @runtime_checkable
 class KeyValueProtocol(Protocol):
-    """A subset of KV operations: get/put/delete and TTL variants, including bulk calls."""
+    """A subset of KV operations: get/put/delete and TTL variants, including bulk calls.
+
+    This protocol defines the minimal contract for key-value store implementations. All methods are
+    async and may raise exceptions on connection failures, validation errors, or other operational issues.
+    Implementations should handle backend-specific errors appropriately.
+    """
 
     def get(self, key: str, *, collection: str | None = None) -> dict[str, Any] | None:
         """Retrieve a value by key from the specified collection.
@@ -52,6 +57,9 @@ def delete(self, key: str, *, collection: str | None = None) -> bool:
         Args:
             key: The key to delete the value from.
             collection: The collection to delete the value from. If no collection is provided, it will use the default collection.
+
+        Returns:
+            True if the key was deleted, False if the key did not exist.
         """
         ...
 

key-value/key-value-sync/src/key_value/sync/code_gen/stores/base.py

@@ -35,6 +35,18 @@
 
 
 def _seed_to_frozen_seed_data(seed: SEED_DATA_TYPE) -> FROZEN_SEED_DATA_TYPE:
+    """Convert mutable seed data to an immutable frozen structure.
+
+    This function converts the nested mapping structure of seed data into immutable MappingProxyType
+    objects at all levels. Using immutable structures prevents accidental modification of seed data
+    after store initialization and ensures thread-safety.
+
+    Args:
+        seed: The mutable seed data mapping: {collection: {key: {field: value}}}.
+
+    Returns:
+        An immutable frozen version of the seed data using MappingProxyType.
+    """
     return MappingProxyType(
         {
             collection: MappingProxyType({key: MappingProxyType(value) for (key, value) in items.items()})
@@ -107,6 +119,15 @@ def _seed_store(self) -> None:
                 self.put(key=key, value=dict(value), collection=collection)
 
     def setup(self) -> None:
+        """Initialize the store if not already initialized.
+
+        This method is called automatically before any store operations and uses a lock to ensure
+        thread-safe lazy initialization. It can also be called manually to ensure the store is ready
+        before performing operations. The setup process includes calling the `_setup()` hook and
+        seeding the store with initial data if provided.
+
+        This method is idempotent - calling it multiple times has no additional effect after the first call.
+        """
         if not self._setup_complete:
             with self._setup_lock:
                 if not self._setup_complete:
@@ -122,6 +143,19 @@ def setup(self) -> None:
                     self._seed_store()
 
     def setup_collection(self, *, collection: str) -> None:
+        """Initialize a specific collection if not already initialized.
+
+        This method is called automatically before any collection-specific operations and uses a per-collection
+        lock to ensure thread-safe lazy initialization. It can also be called manually to ensure a collection
+        is ready before performing operations on it. The setup process includes calling the `_setup_collection()`
+        hook for store-specific collection initialization.
+
+        This method is idempotent - calling it multiple times for the same collection has no additional effect
+        after the first call.
+
+        Args:
+            collection: The name of the collection to initialize.
+        """
         self.setup()
 
         if not self._setup_collection_complete[collection]:
@@ -218,6 +252,7 @@ def _put_managed_entries(
         created_at: datetime,
         expires_at: datetime | None,
     ) -> None:
+
         """Store multiple managed entries by key in the specified collection.
 
         Args:

key-value/key-value-sync/src/key_value/sync/code_gen/stores/memory/store.py

@@ -148,28 +148,42 @@ def _setup_collection(self, *, collection: str) -> None:
         collection_cache = MemoryCollection(max_entries=self.max_entries_per_collection)
         self._cache[collection] = collection_cache
 
+    def _get_collection_or_raise(self, collection: str) -> MemoryCollection:
+        """Get a collection or raise KeyError if not setup.
+
+        Args:
+            collection: The collection name.
+
+        Returns:
+            The MemoryCollection instance.
+
+        Raises:
+            KeyError: If the collection has not been setup via setup_collection().
+        """
+        collection_cache: MemoryCollection | None = self._cache.get(collection)
+        if collection_cache is None:
+            msg = f"Collection '{collection}' has not been setup. Call setup_collection() first."
+            raise KeyError(msg)
+        return collection_cache
+
     @override
     def _get_managed_entry(self, *, key: str, collection: str) -> ManagedEntry | None:
-        collection_cache: MemoryCollection = self._cache[collection]
-
+        collection_cache = self._get_collection_or_raise(collection)
         return collection_cache.get(key=key)
 
     @override
     def _put_managed_entry(self, *, key: str, collection: str, managed_entry: ManagedEntry) -> None:
-        collection_cache: MemoryCollection = self._cache[collection]
-
+        collection_cache = self._get_collection_or_raise(collection)
         collection_cache.put(key=key, value=managed_entry)
 
     @override
     def _delete_managed_entry(self, *, key: str, collection: str) -> bool:
-        collection_cache: MemoryCollection = self._cache[collection]
-
+        collection_cache = self._get_collection_or_raise(collection)
         return collection_cache.delete(key=key)
 
     @override
     def _get_collection_keys(self, *, collection: str, limit: int | None = None) -> list[str]:
-        collection_cache: MemoryCollection = self._cache[collection]
-
+        collection_cache = self._get_collection_or_raise(collection)
         return collection_cache.keys(limit=limit)
 
     @override

key-value/key-value-sync/src/key_value/sync/code_gen/stores/mongodb/store.py

@@ -41,15 +41,34 @@
 
 
 def document_to_managed_entry(document: dict[str, Any]) -> ManagedEntry:
-    """
-    Convert a MongoDB document to a ManagedEntry.
+    """Convert a MongoDB document back to a ManagedEntry.
+
+    This function deserializes a MongoDB document (created by `managed_entry_to_document`) back to a
+    ManagedEntry object, parsing the stringified value field and preserving all metadata.
+
+    Args:
+        document: The MongoDB document to convert.
+
+    Returns:
+        A ManagedEntry object reconstructed from the document.
     """
     return ManagedEntry.from_dict(data=document, stringified_value=True)
 
 
 def managed_entry_to_document(key: str, managed_entry: ManagedEntry) -> dict[str, Any]:
-    """
-    Convert a ManagedEntry to a MongoDB document.
+    """Convert a ManagedEntry to a MongoDB document for storage.
+
+    This function serializes a ManagedEntry to a MongoDB document format, including the key and all
+    metadata (TTL, creation, and expiration timestamps). The value is stringified to ensure proper
+    storage in MongoDB. The serialization is designed to preserve all entry information for round-trip
+    conversion back to a ManagedEntry.
+
+    Args:
+        key: The key associated with this entry.
+        managed_entry: The ManagedEntry to serialize.
+
+    Returns:
+        A MongoDB document dict containing the key, value, and all metadata.
     """
     return {
         "key": key,
@@ -134,6 +153,18 @@ def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:  # pyright
         self._client.__exit__(exc_type, exc_val, exc_tb)
 
     def _sanitize_collection_name(self, collection: str) -> str:
+        """Sanitize a collection name to meet MongoDB naming requirements.
+
+        MongoDB has specific requirements for collection names (length limits, allowed characters).
+        This method ensures collection names are compliant by truncating to the maximum allowed length
+        and replacing invalid characters with safe alternatives.
+
+        Args:
+            collection: The collection name to sanitize.
+
+        Returns:
+            A sanitized collection name that meets MongoDB requirements.
+        """
         return sanitize_string(value=collection, max_length=MAX_COLLECTION_LENGTH, allowed_characters=ALPHANUMERIC_CHARACTERS)
 
     @override

key-value/key-value-sync/src/key_value/sync/code_gen/stores/redis/store.py

@@ -24,15 +24,32 @@
 
 
 def managed_entry_to_json(managed_entry: ManagedEntry) -> str:
-    """
-    Convert a ManagedEntry to a JSON string.
+    """Convert a ManagedEntry to a JSON string for Redis storage.
+
+    This function serializes a ManagedEntry to JSON format including all metadata (TTL, creation,
+    and expiration timestamps). The serialization is designed to preserve all entry information
+    for round-trip conversion back to a ManagedEntry.
+
+    Args:
+        managed_entry: The ManagedEntry to serialize.
+
+    Returns:
+        A JSON string representation of the ManagedEntry with full metadata.
     """
     return managed_entry.to_json(include_metadata=True, include_expiration=True, include_creation=True)
 
 
 def json_to_managed_entry(json_str: str) -> ManagedEntry:
-    """
-    Convert a JSON string to a ManagedEntry.
+    """Convert a JSON string from Redis storage back to a ManagedEntry.
+
+    This function deserializes a JSON string (created by `managed_entry_to_json`) back to a
+    ManagedEntry object, preserving all metadata including TTL, creation, and expiration timestamps.
+
+    Args:
+        json_str: The JSON string to deserialize.
+
+    Returns:
+        A ManagedEntry object reconstructed from the JSON string.
     """
     return ManagedEntry.from_json(json_str=json_str, includes_metadata=True)
 

key-value/key-value-sync/src/key_value/sync/code_gen/wrappers/base.py

@@ -11,7 +11,24 @@
 
 
 class BaseWrapper(KeyValue):
-    """A base wrapper for KVStore implementations that passes through to the underlying store."""
+    """A base wrapper for KVStore implementations that passes through to the underlying store.
+
+    This class implements the passthrough pattern where all operations are delegated to the wrapped
+    key-value store without modification. It serves as a foundation for creating custom wrappers that
+    need to intercept, modify, or enhance specific operations while passing through others unchanged.
+
+    To create a custom wrapper, subclass this class and override only the methods you need to customize.
+    All other operations will automatically pass through to the underlying store.
+
+    Example:
+        class LoggingWrapper(BaseWrapper):
+            async def get(self, key: str, *, collection: str | None = None):
+                logger.info(f"Getting key: {key}")
+                return await super().get(key, collection=collection)
+
+    Attributes:
+        key_value: The underlying KeyValue store that operations are delegated to.
+    """
 
     key_value: KeyValue
 

key-value/key-value-sync/src/key_value/sync/code_gen/wrappers/default_value/wrapper.py

@@ -38,6 +38,8 @@ def __init__(self, key_value: KeyValue, default_value: Mapping[str, Any], defaul
         self._default_value_json = dump_to_json(obj=dict(default_value))
         self._default_ttl = None if default_ttl is None else float(default_ttl)
 
+        super().__init__()
+
     def _new_default_value(self) -> dict[str, Any]:
         return load_from_json(json_str=self._default_value_json)