feat: Extend sanitization strategy pattern to all stores

Apply the sanitization strategy pattern (from Elasticsearch store) to all
stores that perform sanitization. This ensures consistent behavior across all
stores: sanitization is now opt-in rather than automatic, avoiding surprising
transformations of user keys and collections.

Changes:
- MongoDB: Added optional collection_sanitization_strategy parameter
  - Defaults to PassthroughStrategy() (no sanitization)
  - Created MongoDBV1CollectionSanitizationStrategy for backward compatibility

- Keyring: Added optional key/collection sanitization strategy parameters
  - Defaults to PassthroughStrategy() (no sanitization)
  - Created KeyringV1SanitizationStrategy for backward compatibility

- Windows Registry: Added optional key/collection sanitization strategy parameters
  - Defaults to PassthroughStrategy() (no sanitization)
  - Created WindowsRegistryV1SanitizationStrategy for backward compatibility

- Memcached: Added optional key_sanitization_strategy parameter
  - Defaults to PassthroughStrategy() (no sanitization)
  - Created MemcachedV1KeySanitizationStrategy for backward compatibility
  - Removed custom sanitize_key method, now uses base class _sanitize_key

All stores now follow the same pattern:
1. Accept optional sanitization strategy parameters in __init__
2. Default to PassthroughStrategy() to avoid surprising transformations
3. Provide V1 strategy classes that encapsulate previous hardcoded behavior
4. Update docstrings to explain sanitization options and limitations

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

Co-authored-by: William Easton <[email protected]>

Author: github-actions[bot]

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

@@ -1,8 +1,10 @@
 """Python keyring-based key-value store."""
 
+from typing import Any
+
 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
+from key_value.shared.utils.sanitization import HybridSanitizationStrategy, PassthroughStrategy, SanitizationStrategy
 from key_value.shared.utils.sanitize import ALPHANUMERIC_CHARACTERS
 from typing_extensions import override
 
@@ -21,12 +23,26 @@
 ALLOWED_KEY_COLLECTION_CHARACTERS: str = ALPHANUMERIC_CHARACTERS
 
 
+class KeyringV1SanitizationStrategy(HybridSanitizationStrategy):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
+        super().__init__(
+            replacement_character="_",
+            max_length=MAX_KEY_COLLECTION_LENGTH,
+            allowed_characters=ALLOWED_KEY_COLLECTION_CHARACTERS,
+        )
+
+
 class KeyringStore(BaseStore):
     """Python keyring-based key-value store using keyring library.
 
     This store uses the Python keyring to persist key-value pairs. Each entry is stored
     as a password in the keychain with the combination of collection and key as the username.
 
+    By default, keys and collections are not sanitized. This means that there are character and length restrictions on
+    keys and collections that may cause errors when trying to get and put entries.
+
+    To avoid issues, you may want to consider leveraging the `KeyringV1SanitizationStrategy` strategy.
+
     Note: TTL is not natively supported by Python keyring, so TTL information is stored
     within the JSON payload and checked at retrieval time.
     """
@@ -38,23 +54,23 @@ def __init__(
         *,
         service_name: str = DEFAULT_KEYCHAIN_SERVICE,
         default_collection: str | None = None,
+        key_sanitization_strategy: SanitizationStrategy | None = None,
+        collection_sanitization_strategy: SanitizationStrategy | None = None,
     ) -> None:
         """Initialize the Python keyring store.
 
         Args:
             service_name: The service name to use in the keychain. Defaults to "py-key-value".
             default_collection: The default collection to use if no collection is provided.
+            key_sanitization_strategy: The sanitization strategy to use for keys.
+            collection_sanitization_strategy: The sanitization strategy to use for collections.
         """
         self._service_name = service_name
 
-        sanitization_strategy = HybridSanitizationStrategy(
-            replacement_character="_", max_length=MAX_KEY_COLLECTION_LENGTH, allowed_characters=ALLOWED_KEY_COLLECTION_CHARACTERS
-        )
-
         super().__init__(
             default_collection=default_collection,
-            collection_sanitization_strategy=sanitization_strategy,
-            key_sanitization_strategy=sanitization_strategy,
+            collection_sanitization_strategy=collection_sanitization_strategy or PassthroughStrategy(),
+            key_sanitization_strategy=key_sanitization_strategy or PassthroughStrategy(),
         )
 
     @override

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

@@ -1,10 +1,9 @@
-import hashlib
 from collections.abc import Sequence
-from typing import overload
+from typing import Any, overload
 
 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 HashExcessLengthStrategy
+from key_value.shared.utils.sanitization import HashExcessLengthStrategy, PassthroughStrategy, SanitizationStrategy
 from typing_extensions import override
 
 from key_value.aio.stores.base import BaseContextManagerStore, BaseDestroyStore, BaseStore
@@ -18,16 +17,36 @@
 MAX_KEY_LENGTH = 240
 
 
+class MemcachedV1KeySanitizationStrategy(HashExcessLengthStrategy):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
+        super().__init__(max_length=MAX_KEY_LENGTH)
+
+
 class MemcachedStore(BaseDestroyStore, BaseContextManagerStore, BaseStore):
-    """Memcached-based key-value store using aiomcache."""
+    """Memcached-based key-value store using aiomcache.
+
+    By default, keys are not sanitized. This means that there are character and length restrictions on
+    keys that may cause errors when trying to get and put entries.
+
+    To avoid issues, you may want to consider leveraging the `MemcachedV1KeySanitizationStrategy` strategy.
+    """
 
     _client: Client
 
     @overload
-    def __init__(self, *, client: Client, default_collection: str | None = None) -> None: ...
+    def __init__(
+        self, *, client: Client, default_collection: str | None = None, key_sanitization_strategy: SanitizationStrategy | None = None
+    ) -> None: ...
 
     @overload
-    def __init__(self, *, host: str = "127.0.0.1", port: int = 11211, default_collection: str | None = None) -> None: ...
+    def __init__(
+        self,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 11211,
+        default_collection: str | None = None,
+        key_sanitization_strategy: SanitizationStrategy | None = None,
+    ) -> None: ...
 
     def __init__(
         self,
@@ -36,6 +55,7 @@ def __init__(
         host: str = "127.0.0.1",
         port: int = 11211,
         default_collection: str | None = None,
+        key_sanitization_strategy: SanitizationStrategy | None = None,
     ) -> None:
         """Initialize the Memcached store.
 
@@ -44,25 +64,18 @@ def __init__(
             host: Memcached host. Defaults to 127.0.0.1.
             port: Memcached port. Defaults to 11211.
             default_collection: The default collection to use if no collection is provided.
+            key_sanitization_strategy: The sanitization strategy to use for keys.
         """
         self._client = client or Client(host=host, port=port)
 
-        sanitization_strategy = HashExcessLengthStrategy(max_length=MAX_KEY_LENGTH)
-
         super().__init__(
             default_collection=default_collection,
-            key_sanitization_strategy=sanitization_strategy,
+            key_sanitization_strategy=key_sanitization_strategy or PassthroughStrategy(),
         )
 
-    def sanitize_key(self, key: str) -> str:
-        if len(key) > MAX_KEY_LENGTH:
-            sha256_hash: str = hashlib.sha256(key.encode()).hexdigest()
-            return sha256_hash[:64]
-        return key
-
     @override
     async def _get_managed_entry(self, *, key: str, collection: str) -> ManagedEntry | None:
-        combo_key: str = self.sanitize_key(compound_key(collection=collection, key=key))
+        combo_key: str = self._sanitize_key(compound_key(collection=collection, key=key))
 
         raw_value: bytes | None = await self._client.get(combo_key.encode("utf-8"))
 
@@ -78,7 +91,7 @@ async def _get_managed_entries(self, *, collection: str, keys: Sequence[str]) ->
         if not keys:
             return []
 
-        combo_keys: list[str] = [self.sanitize_key(compound_key(collection=collection, key=key)) for key in keys]
+        combo_keys: list[str] = [self._sanitize_key(compound_key(collection=collection, key=key)) for key in keys]
 
         # Use multi_get for efficient batch retrieval
         # multi_get returns a tuple in the same order as keys
@@ -102,7 +115,7 @@ async def _put_managed_entry(
         collection: str,
         managed_entry: ManagedEntry,
     ) -> None:
-        combo_key: str = self.sanitize_key(compound_key(collection=collection, key=key))
+        combo_key: str = self._sanitize_key(compound_key(collection=collection, key=key))
 
         # Memcached treats 0 as no-expiration. Do not pass <= 0 (other than 0) to avoid permanence errors.
         exptime: int
@@ -122,7 +135,7 @@ async def _put_managed_entry(
 
     @override
     async def _delete_managed_entry(self, *, key: str, collection: str) -> bool:
-        combo_key: str = self.sanitize_key(compound_key(collection=collection, key=key))
+        combo_key: str = self._sanitize_key(compound_key(collection=collection, key=key))
 
         return await self._client.delete(key=combo_key.encode(encoding="utf-8"))
 

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

@@ -5,7 +5,7 @@
 from bson.errors import InvalidDocument
 from key_value.shared.errors import DeserializationError, SerializationError
 from key_value.shared.utils.managed_entry import ManagedEntry
-from key_value.shared.utils.sanitization import HybridSanitizationStrategy
+from key_value.shared.utils.sanitization import HybridSanitizationStrategy, PassthroughStrategy, SanitizationStrategy
 from key_value.shared.utils.sanitize import ALPHANUMERIC_CHARACTERS
 from key_value.shared.utils.serialization import SerializationAdapter
 from typing_extensions import Self, override
@@ -89,8 +89,25 @@ def prepare_load(self, data: dict[str, Any]) -> dict[str, Any]:
         return data
 
 
+class MongoDBV1CollectionSanitizationStrategy(HybridSanitizationStrategy):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
+        super().__init__(
+            replacement_character="_",
+            max_length=MAX_COLLECTION_LENGTH,
+            allowed_characters=COLLECTION_ALLOWED_CHARACTERS,
+        )
+
+
 class MongoDBStore(BaseDestroyCollectionStore, BaseContextManagerStore, BaseStore):
-    """MongoDB-based key-value store using pymongo."""
+    """MongoDB-based key-value store using pymongo.
+
+    Stores collections as MongoDB collections and stores values in document fields.
+
+    By default, collections are not sanitized. This means that there are character and length restrictions on
+    collection names that may cause errors when trying to get and put entries.
+
+    To avoid issues, you may want to consider leveraging the `MongoDBV1CollectionSanitizationStrategy` strategy.
+    """
 
     _client: AsyncMongoClient[dict[str, Any]]
     _db: AsyncDatabase[dict[str, Any]]
@@ -106,6 +123,7 @@ def __init__(
         coll_name: str | None = None,
         native_storage: bool = True,
         default_collection: str | None = None,
+        collection_sanitization_strategy: SanitizationStrategy | None = None,
     ) -> None:
         """Initialize the MongoDB store.
 
@@ -115,6 +133,7 @@ def __init__(
             coll_name: The name of the MongoDB collection.
             native_storage: Whether to use native BSON storage (True, default) or JSON string storage (False).
             default_collection: The default collection to use if no collection is provided.
+            collection_sanitization_strategy: The sanitization strategy to use for collections.
         """
 
     @overload
@@ -126,6 +145,7 @@ def __init__(
         coll_name: str | None = None,
         native_storage: bool = True,
         default_collection: str | None = None,
+        collection_sanitization_strategy: SanitizationStrategy | None = None,
     ) -> None:
         """Initialize the MongoDB store.
 
@@ -135,6 +155,7 @@ def __init__(
             coll_name: The name of the MongoDB collection.
             native_storage: Whether to use native BSON storage (True, default) or JSON string storage (False).
             default_collection: The default collection to use if no collection is provided.
+            collection_sanitization_strategy: The sanitization strategy to use for collections.
         """
 
     def __init__(
@@ -146,6 +167,7 @@ def __init__(
         coll_name: str | None = None,
         native_storage: bool = True,
         default_collection: str | None = None,
+        collection_sanitization_strategy: SanitizationStrategy | None = None,
     ) -> None:
         """Initialize the MongoDB store.
 
@@ -158,6 +180,7 @@ def __init__(
                            Native storage stores values as BSON dicts for better query support.
                            Legacy mode stores values as JSON strings for backward compatibility.
             default_collection: The default collection to use if no collection is provided.
+            collection_sanitization_strategy: The sanitization strategy to use for collections.
         """
 
         if client:
@@ -177,9 +200,7 @@ def __init__(
 
         super().__init__(
             default_collection=default_collection,
-            collection_sanitization_strategy=HybridSanitizationStrategy(
-                replacement_character="_", max_length=MAX_COLLECTION_LENGTH, allowed_characters=COLLECTION_ALLOWED_CHARACTERS
-            ),
+            collection_sanitization_strategy=collection_sanitization_strategy or PassthroughStrategy(),
         )
 
     @override

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

@@ -1,10 +1,10 @@
 """Windows Registry-based key-value store."""
 
-from typing import Literal
+from typing import Any, Literal
 from winreg import HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE
 
 from key_value.shared.utils.managed_entry import ManagedEntry
-from key_value.shared.utils.sanitization import HybridSanitizationStrategy
+from key_value.shared.utils.sanitization import HybridSanitizationStrategy, PassthroughStrategy, SanitizationStrategy
 from key_value.shared.utils.sanitize import ALPHANUMERIC_CHARACTERS
 from typing_extensions import override
 
@@ -25,12 +25,25 @@
 ALLOWED_KEY_COLLECTION_CHARACTERS: str = ALPHANUMERIC_CHARACTERS
 
 
+class WindowsRegistryV1SanitizationStrategy(HybridSanitizationStrategy):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
+        super().__init__(
+            max_length=MAX_KEY_COLLECTION_LENGTH,
+            allowed_characters=ALLOWED_KEY_COLLECTION_CHARACTERS,
+        )
+
+
 class WindowsRegistryStore(BaseStore):
     """Windows Registry-based key-value store.
 
     This store uses the Windows Registry to persist key-value pairs. Each entry is stored
     as a string value in the registry under HKEY_CURRENT_USER\\Software\\{root}\\{collection}\\{key}.
 
+    By default, keys and collections are not sanitized. This means that there are character and length restrictions on
+    keys and collections that may cause errors when trying to get and put entries.
+
+    To avoid issues, you may want to consider leveraging the `WindowsRegistryV1SanitizationStrategy` strategy.
+
     Note: TTL is not natively supported by Windows Registry, so TTL information is stored
     within the JSON payload and checked at retrieval time.
     """
@@ -41,25 +54,25 @@ def __init__(
         hive: Literal["HKEY_CURRENT_USER", "HKEY_LOCAL_MACHINE"] | None = None,
         registry_path: str | None = None,
         default_collection: str | None = None,
+        key_sanitization_strategy: SanitizationStrategy | None = None,
+        collection_sanitization_strategy: SanitizationStrategy | None = None,
     ) -> None:
         """Initialize the Windows Registry store.
 
         Args:
             hive: The hive to use. Defaults to "HKEY_CURRENT_USER".
             registry_path: The registry path to use. Must be a valid registry path under the hive. Defaults to "Software\\py-key-value".
             default_collection: The default collection to use if no collection is provided.
+            key_sanitization_strategy: The sanitization strategy to use for keys.
+            collection_sanitization_strategy: The sanitization strategy to use for collections.
         """
         self._hive = HKEY_LOCAL_MACHINE if hive == "HKEY_LOCAL_MACHINE" else HKEY_CURRENT_USER
         self._registry_path = registry_path or DEFAULT_REGISTRY_PATH
 
-        sanitization_strategy = HybridSanitizationStrategy(
-            max_length=MAX_KEY_COLLECTION_LENGTH, allowed_characters=ALLOWED_KEY_COLLECTION_CHARACTERS
-        )
-
         super().__init__(
             default_collection=default_collection,
-            key_sanitization_strategy=sanitization_strategy,
-            collection_sanitization_strategy=sanitization_strategy,
+            key_sanitization_strategy=key_sanitization_strategy or PassthroughStrategy(),
+            collection_sanitization_strategy=collection_sanitization_strategy or PassthroughStrategy(),
         )
 
     def _get_registry_path(self, *, collection: str) -> str:

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

@@ -66,7 +66,7 @@
 MAX_KEY_LENGTH = 256
 ALLOWED_KEY_CHARACTERS: str = ALPHANUMERIC_CHARACTERS
 
-MAX_INDEX_LENGTH = 240
+MAX_INDEX_LENGTH = 200
 ALLOWED_INDEX_CHARACTERS: str = LOWERCASE_ALPHABET + NUMBERS + "_" + "-" + "."
 
 
@@ -97,7 +97,7 @@ def prepare_load(self, data: dict[str, Any]) -> dict[str, Any]:
 
 class ElasticsearchV1KeySanitizationStrategy(AlwaysHashStrategy):
     def __init__(self, *args: Any, **kwargs: Any) -> None:
-        super().__init__(hash_length=MAX_KEY_LENGTH)
+        super().__init__(hash_length=64)
 
 
 class ElasticsearchV1CollectionSanitizationStrategy(HybridSanitizationStrategy):
@@ -175,8 +175,6 @@ def __init__(
             api_key: The api key to use.
             index_prefix: The index prefix to use. Collections will be prefixed with this prefix.
             default_collection: The default collection to use if no collection is provided.
-            key_sanitization_strategy: The sanitization strategy to use for keys.
-            collection_sanitization_strategy: The sanitization strategy to use for collections.
         """
 
     def __init__(