refactor: Rename SanitizationMigrationWrapper to MigrationWrapper

The wrapper is already generic and doesn't depend on sanitization
strategies. It manages dual-store migration with caching and lazy
migration, making it useful for various migration scenarios:
- Sanitization strategy changes
- Encryption configuration changes
- Compression setting changes
- Backend store migrations

Changes:
- Renamed SanitizationMigrationWrapper to MigrationWrapper
- Renamed sanitization_migration directory to migration
- Updated all imports and references
- Added pytest-asyncio markers to test files
- Updated documentation with generic examples
- Regenerated sync code

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

Author: github-actions[bot]

key-value/key-value-aio/src/key_value/aio/wrappers/migration/__init__.py

@@ -0,0 +1,9 @@
+"""Migration wrapper for gradual store transitions.
+
+This module provides a wrapper that enables gradual migration between two stores
+(e.g., stores with different configurations) without breaking access to existing data.
+"""
+
+from key_value.aio.wrappers.migration.wrapper import MigrationWrapper
+
+__all__ = ["MigrationWrapper"]

key-value/key-value-aio/src/key_value/aio/wrappers/sanitization_migration/wrapper.py renamed to key-value/key-value-aio/src/key_value/aio/wrappers/migration/wrapper.py

@@ -1,12 +1,12 @@
-"""Wrapper for migrating between sanitization strategies.
+"""Wrapper for migrating between two key-value stores.
 
-This wrapper enables gradual migration from one sanitization strategy to another
-without breaking access to existing data. It wraps two stores configured with
-different sanitization strategies and provides:
+This wrapper enables gradual migration from one store configuration to another
+without breaking access to existing data. It wraps two stores (current and legacy)
+and provides:
 
-1. **Collision detection**: Skips migration if both strategies produce the same key
+1. **Dual-store read**: Tries current store first, falls back to legacy
 2. **LRU caching**: Caches lookup results to avoid repeated fallback checks
-3. **Lazy migration**: Optionally migrates keys from old to new format on read
+3. **Lazy migration**: Optionally migrates keys from legacy to current on read
 """
 
 from collections.abc import Mapping, Sequence
@@ -19,47 +19,52 @@
 from key_value.aio.wrappers.base import BaseWrapper
 
 
-class SanitizationMigrationWrapper(BaseWrapper):
-    """Wrapper for migrating between sanitization strategies.
+class MigrationWrapper(BaseWrapper):
+    """Wrapper for migrating between two key-value stores.
 
-    This wrapper manages the transition between two stores using different sanitization
-    strategies. It tries the current store first, then falls back to the legacy store
-    if the key is not found. Optionally, it can migrate keys from the legacy store to
-    the current store on read.
+    This wrapper manages the transition between two stores (e.g., stores with different
+    configurations such as sanitization strategies, encryption, compression, etc.).
+    It tries the current store first, then falls back to the legacy store if the key
+    is not found. Optionally, it can migrate keys from the legacy store to the current
+    store on read.
 
     The wrapper includes:
-    - **Collision detection**: If both strategies produce the same sanitized key, no
-      fallback is performed (no migration needed)
+    - **Dual-store read**: Tries current store first, falls back to legacy
     - **LRU cache**: Caches which keys are in current vs. legacy store to avoid
       repeated lookups
     - **Lazy migration**: Optionally copies data from legacy to current store on read
 
-    Example:
+    Common use cases:
+    - Migrating between sanitization strategies
+    - Migrating between encryption configurations
+    - Migrating between compression settings
+    - Migrating between different backend stores
+
+    Example (sanitization strategy migration):
         ```python
         from key_value.aio.stores.memcached import MemcachedStore
         from key_value.shared.utils.sanitization_strategy import (
             HashLongKeysSanitizationStrategy,
         )
-        from key_value.aio.wrappers.sanitization_migration import (
-            SanitizationMigrationWrapper,
-        )
+        from key_value.aio.wrappers.migration import MigrationWrapper
 
-        # Old strategy (no prefix - collision risk!)
-        old_strategy = HashLongKeysSanitizationStrategy(max_length=240)
+        # Legacy store with old configuration
         legacy_store = MemcachedStore(
             host="localhost",
-            sanitization_strategy=old_strategy,
+            sanitization_strategy=HashLongKeysSanitizationStrategy(max_length=240),
         )
 
-        # New strategy (with H_ prefix - collision safe)
-        new_strategy = HashLongKeysSanitizationStrategy(max_length=240)
+        # Current store with new configuration
         current_store = MemcachedStore(
             host="localhost",
-            sanitization_strategy=new_strategy,
+            sanitization_strategy=HashLongKeysSanitizationStrategy(
+                max_length=240,
+                add_prefix=True,
+            ),
         )
 
         # Wrap with migration support
-        migrating_store = SanitizationMigrationWrapper(
+        migrating_store = MigrationWrapper(
             current_store=current_store,
             legacy_store=legacy_store,
             migrate_on_read=True,  # Copy old data to new location
@@ -68,8 +73,8 @@ class SanitizationMigrationWrapper(BaseWrapper):
         ```
 
     Args:
-        current_store: Store using the new sanitization strategy.
-        legacy_store: Store using the old sanitization strategy.
+        current_store: The target store (new configuration).
+        legacy_store: The source store (old configuration).
         migrate_on_read: If True, copy keys from legacy to current on read.
         delete_after_migration: If True, delete from legacy after migration.
         cache_size: Maximum number of keys to cache. Set to 0 to disable caching.
@@ -94,8 +99,8 @@ def __init__(
         """Initialize the migration wrapper.
 
         Args:
-            current_store: Store using the new sanitization strategy.
-            legacy_store: Store using the old sanitization strategy.
+            current_store: The target store (new configuration).
+            legacy_store: The source store (old configuration).
             migrate_on_read: If True, copy keys from legacy to current on read.
             delete_after_migration: If True, delete from legacy after migration.
             cache_size: Maximum number of keys to cache. Set to 0 to disable.

key-value/key-value-aio/src/key_value/aio/wrappers/sanitization_migration/__init__.py

@@ -1,13 +1,15 @@
-"""Tests for SanitizationMigrationWrapper."""
+"""Tests for MigrationWrapper."""
 
 import pytest
 
 from key_value.aio.stores.memory import MemoryStore
-from key_value.aio.wrappers.sanitization_migration import SanitizationMigrationWrapper
+from key_value.aio.wrappers.migration import MigrationWrapper
 
+pytestmark = pytest.mark.asyncio
 
-class TestSanitizationMigrationWrapper:
-    """Tests for SanitizationMigrationWrapper."""
+
+class TestMigrationWrapper:
+    """Tests for MigrationWrapper."""
 
     @pytest.fixture
     def current_store(self) -> MemoryStore:
@@ -20,37 +22,35 @@ def legacy_store(self) -> MemoryStore:
         return MemoryStore()
 
     @pytest.fixture
-    def wrapper(self, current_store: MemoryStore, legacy_store: MemoryStore) -> SanitizationMigrationWrapper:
+    def wrapper(self, current_store: MemoryStore, legacy_store: MemoryStore) -> MigrationWrapper:
         """Create a migration wrapper."""
-        return SanitizationMigrationWrapper(
+        return MigrationWrapper(
             current_store=current_store,
             legacy_store=legacy_store,
             migrate_on_read=False,
             cache_size=100,
         )
 
     @pytest.fixture
-    def migrating_wrapper(self, current_store: MemoryStore, legacy_store: MemoryStore) -> SanitizationMigrationWrapper:
+    def migrating_wrapper(self, current_store: MemoryStore, legacy_store: MemoryStore) -> MigrationWrapper:
         """Create a migration wrapper with migrate_on_read=True."""
-        return SanitizationMigrationWrapper(
+        return MigrationWrapper(
             current_store=current_store,
             legacy_store=legacy_store,
             migrate_on_read=True,
             delete_after_migration=False,
             cache_size=100,
         )
 
-    async def test_get_from_current_store(self, wrapper: SanitizationMigrationWrapper, current_store: MemoryStore) -> None:
+    async def test_get_from_current_store(self, wrapper: MigrationWrapper, current_store: MemoryStore) -> None:
         """Test getting a value from the current store."""
         await current_store.put(key="test_key", value={"data": "current"}, collection="default")
 
         result = await wrapper.get(key="test_key", collection="default")
         assert result is not None
         assert result["data"] == "current"
 
-    async def test_get_from_legacy_store(
-        self, wrapper: SanitizationMigrationWrapper, legacy_store: MemoryStore, current_store: MemoryStore
-    ) -> None:
+    async def test_get_from_legacy_store(self, wrapper: MigrationWrapper, legacy_store: MemoryStore, current_store: MemoryStore) -> None:
         """Test getting a value from the legacy store when not in current."""
         await legacy_store.put(key="test_key", value={"data": "legacy"}, collection="default")
 
@@ -62,13 +62,13 @@ async def test_get_from_legacy_store(
         current_result = await current_store.get(key="test_key", collection="default")
         assert current_result is None
 
-    async def test_get_missing_key(self, wrapper: SanitizationMigrationWrapper) -> None:
+    async def test_get_missing_key(self, wrapper: MigrationWrapper) -> None:
         """Test getting a missing key returns None."""
         result = await wrapper.get(key="missing_key", collection="default")
         assert result is None
 
     async def test_migrate_on_read(
-        self, migrating_wrapper: SanitizationMigrationWrapper, legacy_store: MemoryStore, current_store: MemoryStore
+        self, migrating_wrapper: MigrationWrapper, legacy_store: MemoryStore, current_store: MemoryStore
     ) -> None:
         """Test that migrate_on_read copies data from legacy to current."""
         await legacy_store.put(key="test_key", value={"data": "legacy"}, collection="default", ttl=3600)
@@ -88,7 +88,7 @@ async def test_migrate_on_read(
 
     async def test_migrate_on_read_with_delete(self, legacy_store: MemoryStore, current_store: MemoryStore) -> None:
         """Test that delete_after_migration removes from legacy."""
-        wrapper = SanitizationMigrationWrapper(
+        wrapper = MigrationWrapper(
             current_store=current_store,
             legacy_store=legacy_store,
             migrate_on_read=True,
@@ -106,7 +106,7 @@ async def test_migrate_on_read_with_delete(self, legacy_store: MemoryStore, curr
         assert legacy_result is None
 
     async def test_cache_avoids_repeated_lookups(
-        self, wrapper: SanitizationMigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore
+        self, wrapper: MigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore
     ) -> None:
         """Test that cache avoids repeated lookups."""
         await current_store.put(key="test_key", value={"data": "current"}, collection="default")
@@ -125,7 +125,7 @@ async def test_cache_avoids_repeated_lookups(
         assert result2 is not None
         assert result2["data"] == "current"  # Still from current, not legacy
 
-    async def test_cache_missing_keys(self, wrapper: SanitizationMigrationWrapper) -> None:
+    async def test_cache_missing_keys(self, wrapper: MigrationWrapper) -> None:
         """Test that missing keys are cached."""
         # First get - should cache as missing
         result1 = await wrapper.get(key="missing_key", collection="default")
@@ -139,9 +139,7 @@ async def test_cache_missing_keys(self, wrapper: SanitizationMigrationWrapper) -
         result2 = await wrapper.get(key="missing_key", collection="default")
         assert result2 is None
 
-    async def test_put_updates_cache(
-        self, wrapper: SanitizationMigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore
-    ) -> None:
+    async def test_put_updates_cache(self, wrapper: MigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore) -> None:
         """Test that put updates the cache."""
         # Put initially in legacy
         await legacy_store.put(key="test_key", value={"data": "legacy"}, collection="default")
@@ -159,9 +157,7 @@ async def test_put_updates_cache(
         assert result is not None
         assert result["data"] == "new"
 
-    async def test_delete_from_both_stores(
-        self, wrapper: SanitizationMigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore
-    ) -> None:
+    async def test_delete_from_both_stores(self, wrapper: MigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore) -> None:
         """Test that delete removes from both stores."""
         await current_store.put(key="key1", value={"data": "current"}, collection="default")
         await legacy_store.put(key="key2", value={"data": "legacy"}, collection="default")
@@ -177,7 +173,7 @@ async def test_delete_from_both_stores(
         assert await current_store.get(key="key1", collection="default") is None
         assert await legacy_store.get(key="key2", collection="default") is None
 
-    async def test_get_many(self, wrapper: SanitizationMigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore) -> None:
+    async def test_get_many(self, wrapper: MigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore) -> None:
         """Test get_many with keys in different stores."""
         await current_store.put(key="key1", value={"data": "current1"}, collection="default")
         await legacy_store.put(key="key2", value={"data": "legacy2"}, collection="default")
@@ -192,7 +188,7 @@ async def test_get_many(self, wrapper: SanitizationMigrationWrapper, current_sto
         assert results[2] is None
 
     async def test_get_many_with_migration(
-        self, migrating_wrapper: SanitizationMigrationWrapper, legacy_store: MemoryStore, current_store: MemoryStore
+        self, migrating_wrapper: MigrationWrapper, legacy_store: MemoryStore, current_store: MemoryStore
     ) -> None:
         """Test get_many migrates keys from legacy to current."""
         await legacy_store.put(key="key1", value={"data": "legacy1"}, collection="default")
@@ -210,7 +206,7 @@ async def test_get_many_with_migration(
         assert current_result1 is not None
         assert current_result2 is not None
 
-    async def test_ttl_from_current(self, wrapper: SanitizationMigrationWrapper, current_store: MemoryStore) -> None:
+    async def test_ttl_from_current(self, wrapper: MigrationWrapper, current_store: MemoryStore) -> None:
         """Test ttl from current store."""
         await current_store.put(key="test_key", value={"data": "current"}, collection="default", ttl=3600)
 
@@ -220,9 +216,7 @@ async def test_ttl_from_current(self, wrapper: SanitizationMigrationWrapper, cur
         assert ttl is not None
         assert ttl > 0
 
-    async def test_ttl_from_legacy(
-        self, wrapper: SanitizationMigrationWrapper, legacy_store: MemoryStore, current_store: MemoryStore
-    ) -> None:
+    async def test_ttl_from_legacy(self, wrapper: MigrationWrapper, legacy_store: MemoryStore, current_store: MemoryStore) -> None:
         """Test ttl from legacy store."""
         await legacy_store.put(key="test_key", value={"data": "legacy"}, collection="default", ttl=3600)
 
@@ -236,7 +230,7 @@ async def test_ttl_from_legacy(
         assert current_result is None
 
     async def test_ttl_with_migration(
-        self, migrating_wrapper: SanitizationMigrationWrapper, legacy_store: MemoryStore, current_store: MemoryStore
+        self, migrating_wrapper: MigrationWrapper, legacy_store: MemoryStore, current_store: MemoryStore
     ) -> None:
         """Test ttl migrates from legacy to current."""
         await legacy_store.put(key="test_key", value={"data": "legacy"}, collection="default", ttl=3600)
@@ -250,7 +244,7 @@ async def test_ttl_with_migration(
         assert current_value is not None
         assert current_ttl is not None
 
-    async def test_put_many(self, wrapper: SanitizationMigrationWrapper, current_store: MemoryStore) -> None:
+    async def test_put_many(self, wrapper: MigrationWrapper, current_store: MemoryStore) -> None:
         """Test put_many writes to current store."""
         await wrapper.put_many(
             keys=["key1", "key2"],
@@ -264,7 +258,7 @@ async def test_put_many(self, wrapper: SanitizationMigrationWrapper, current_sto
         assert result1 is not None
         assert result2 is not None
 
-    async def test_delete_many(self, wrapper: SanitizationMigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore) -> None:
+    async def test_delete_many(self, wrapper: MigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore) -> None:
         """Test delete_many removes from both stores."""
         await current_store.put(key="key1", value={"data": "current"}, collection="default")
         await legacy_store.put(key="key2", value={"data": "legacy"}, collection="default")
@@ -278,7 +272,7 @@ async def test_delete_many(self, wrapper: SanitizationMigrationWrapper, current_
 
     async def test_cache_disabled(self, current_store: MemoryStore, legacy_store: MemoryStore) -> None:
         """Test wrapper with caching disabled."""
-        wrapper = SanitizationMigrationWrapper(
+        wrapper = MigrationWrapper(
             current_store=current_store,
             legacy_store=legacy_store,
             cache_size=0,  # Disable cache
@@ -292,7 +286,7 @@ async def test_cache_disabled(self, current_store: MemoryStore, legacy_store: Me
         # Cache should be disabled
         assert not wrapper._cache_enabled  # pyright: ignore[reportPrivateUsage]
 
-    async def test_ttl_many(self, wrapper: SanitizationMigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore) -> None:
+    async def test_ttl_many(self, wrapper: MigrationWrapper, current_store: MemoryStore, legacy_store: MemoryStore) -> None:
         """Test ttl_many with keys in different stores."""
         await current_store.put(key="key1", value={"data": "current1"}, collection="default", ttl=3600)
         await legacy_store.put(key="key2", value={"data": "legacy2"}, collection="default", ttl=7200)

key-value/key-value-aio/tests/wrappers/sanitization_migration/__init__.py renamed to key-value/key-value-aio/tests/wrappers/migration/__init__.py

@@ -0,0 +1,12 @@
+# WARNING: this file is auto-generated by 'build_sync_library.py'
+# from the original file '__init__.py'
+# DO NOT CHANGE! Change the original file instead.
+"""Migration wrapper for gradual store transitions.
+
+This module provides a wrapper that enables gradual migration between two stores
+(e.g., stores with different configurations) without breaking access to existing data.
+"""
+
+from key_value.sync.code_gen.wrappers.migration.wrapper import MigrationWrapper
+
+__all__ = ["MigrationWrapper"]