Update examples to work with refactored API

- Add store extras ([memory], [disk]) to all dependency files
- Fix hatch build configuration in pyproject.toml files
- Update TTLClampWrapper to require both min_ttl and max_ttl
- Update StatisticsWrapper API to use new nested structure
- Update DiskStore parameter from root_directory to directory
- Update RetryWrapper parameter from base_delay to initial_delay
- Update PassthroughCacheWrapper parameters to primary_key_value/cache_key_value
- Update FernetEncryptionWrapper to use fernet instance instead of key
- Update FallbackWrapper parameters to primary_key_value/fallback_key_value
- Update LimitSizeWrapper parameter from max_size_bytes to max_size
- Move StatisticsWrapper to top of stack in trading_data for better tracking
- Add raise_on_decryption_error=False for graceful encryption failures

All tests passing: chat_app (7/7), trading_data (9/9), web_scraper_cache (13/13)

Co-authored-by: William Easton <strawgate@users.noreply.github.com>

Author: github-actions[bot]

examples/chat_app/chat_app.py

@@ -42,10 +42,10 @@ def __init__(self):
 
         # Wrapper stack (applied inside-out):
         # 1. StatisticsWrapper - Track operation metrics
-        # 2. TTLClampWrapper - Enforce max TTL of 24 hours (86400 seconds)
+        # 2. TTLClampWrapper - Enforce TTL between 1 hour and 24 hours
         # 3. LoggingWrapper - Log all operations for debugging
         stats = StatisticsWrapper(key_value=base_store)
-        ttl_clamped = TTLClampWrapper(key_value=stats, max_ttl=86400)  # 24 hours
+        ttl_clamped = TTLClampWrapper(key_value=stats, min_ttl=3600, max_ttl=86400)  # 1 hour min, 24 hours max
         wrapped_store = LoggingWrapper(key_value=ttl_clamped)
 
         # PydanticAdapter for type-safe message storage/retrieval
@@ -112,18 +112,25 @@ async def delete_message(self, conversation_id: str, message_id: str) -> bool:
 
     def get_statistics(self) -> dict[str, int]:
         """
-        Get operation statistics.
+        Get operation statistics across all conversations.
 
         Returns:
-            Dictionary with operation counts (puts, gets, deletes, etc.)
+            Dictionary with aggregated operation counts (puts, gets, deletes, etc.)
         """
         if isinstance(self.stats_wrapper, StatisticsWrapper):
+            # Aggregate statistics across all collections (conversations)
+            total_puts = sum(coll_stats.put.count for coll_stats in self.stats_wrapper.statistics.collections.values())
+            total_gets = sum(coll_stats.get.count for coll_stats in self.stats_wrapper.statistics.collections.values())
+            total_deletes = sum(coll_stats.delete.count for coll_stats in self.stats_wrapper.statistics.collections.values())
+            get_hits = sum(coll_stats.get.hit for coll_stats in self.stats_wrapper.statistics.collections.values())
+            get_misses = sum(coll_stats.get.miss for coll_stats in self.stats_wrapper.statistics.collections.values())
+
             return {
-                "total_puts": self.stats_wrapper.total_puts,
-                "total_gets": self.stats_wrapper.total_gets,
-                "total_deletes": self.stats_wrapper.total_deletes,
-                "get_hits": self.stats_wrapper.get_hits,
-                "get_misses": self.stats_wrapper.get_misses,
+                "total_puts": total_puts,
+                "total_gets": total_gets,
+                "total_deletes": total_deletes,
+                "get_hits": get_hits,
+                "get_misses": get_misses,
             }
         return {}
 

examples/chat_app/pyproject.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "Simple async chat application using py-key-value"
 requires-python = ">=3.10"
 dependencies = [
-    "py-key-value-aio>=0.2.8",
+    "py-key-value-aio[memory]>=0.2.8",
     "pydantic>=2.0.0,<3.0.0",
 ]
 
@@ -17,6 +17,9 @@ dev = [
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

examples/chat_app/requirements.txt

@@ -1,2 +1,2 @@
-py-key-value-aio>=0.2.8
+py-key-value-aio[memory]>=0.2.8
 pydantic>=2.0.0,<3.0.0

examples/trading_data/pyproject.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "Trading data caching using py-key-value with compression and multi-tier caching"
 requires-python = ">=3.10"
 dependencies = [
-    "py-key-value-aio>=0.2.8",
+    "py-key-value-aio[disk,memory]>=0.2.8",
     "pydantic>=2.0.0,<3.0.0",
 ]
 
@@ -17,6 +17,9 @@ dev = [
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

examples/trading_data/requirements.txt

@@ -1,2 +1,2 @@
-py-key-value-aio>=0.2.8
+py-key-value-aio[disk,memory]>=0.2.8
 pydantic>=2.0.0,<3.0.0

examples/trading_data/trading_app.py

@@ -50,22 +50,24 @@ def __init__(self, cache_dir: str = ".trading_cache"):
         memory_cache = MemoryStore()
 
         # Tier 2: Disk cache for historical data
-        disk_cache = DiskStore(root_directory=cache_dir)
+        disk_cache = DiskStore(directory=cache_dir)
 
         # Wrapper stack (applied inside-out):
-        # 1. StatisticsWrapper - Track cache metrics
-        # 2. RetryWrapper - Handle transient failures (3 retries with exponential backoff)
-        # 3. LoggingWrapper - Log operations for debugging
-        # 4. PassthroughCacheWrapper - Two-tier caching (memory → disk)
-        stats = StatisticsWrapper(key_value=disk_cache)
-        retry_wrapper = RetryWrapper(key_value=stats, max_retries=3, base_delay=0.1)
+        # 1. RetryWrapper - Handle transient failures on disk (3 retries with exponential backoff)
+        # 2. LoggingWrapper - Log disk operations for debugging
+        # 3. PassthroughCacheWrapper - Two-tier caching (memory → disk)
+        # 4. StatisticsWrapper - Track all cache metrics (wraps everything)
+        retry_wrapper = RetryWrapper(key_value=disk_cache, max_retries=3, initial_delay=0.1)
         disk_with_logging = LoggingWrapper(key_value=retry_wrapper)
 
-        cache_store = PassthroughCacheWrapper(cache=memory_cache, key_value=disk_with_logging)
+        cache_store = PassthroughCacheWrapper(primary_key_value=disk_with_logging, cache_key_value=memory_cache)
+
+        # Wrap the entire cache stack with statistics to track all operations
+        stats = StatisticsWrapper(key_value=cache_store)
 
         # PydanticAdapter for type-safe price data storage/retrieval
         self.adapter: PydanticAdapter[PriceData] = PydanticAdapter[PriceData](
-            key_value=cache_store,
+            key_value=stats,
             pydantic_model=PriceData,
         )
 
@@ -138,25 +140,28 @@ async def delete_price(self, symbol: str, data_id: str) -> bool:
         """
         return await self.adapter.delete(collection=f"symbol:{symbol}", key=data_id)
 
-    def get_cache_statistics(self) -> dict[str, int]:
+    def get_cache_statistics(self) -> dict[str, int | float]:
         """
-        Get cache performance statistics.
+        Get cache performance statistics across all symbols.
 
         Returns:
-            Dictionary with cache metrics (hits, misses, operations)
+            Dictionary with aggregated cache metrics (hits, misses, operations)
         """
         if isinstance(self.stats_wrapper, StatisticsWrapper):
-            total_gets = self.stats_wrapper.total_gets
-            hits = self.stats_wrapper.get_hits
-            misses = self.stats_wrapper.get_misses
+            # Aggregate statistics across all collections (symbols)
+            total_puts = sum(coll_stats.put.count for coll_stats in self.stats_wrapper.statistics.collections.values())
+            total_gets = sum(coll_stats.get.count for coll_stats in self.stats_wrapper.statistics.collections.values())
+            total_deletes = sum(coll_stats.delete.count for coll_stats in self.stats_wrapper.statistics.collections.values())
+            hits = sum(coll_stats.get.hit for coll_stats in self.stats_wrapper.statistics.collections.values())
+            misses = sum(coll_stats.get.miss for coll_stats in self.stats_wrapper.statistics.collections.values())
 
             return {
                 "total_gets": total_gets,
                 "cache_hits": hits,
                 "cache_misses": misses,
                 "hit_rate_percent": round((hits / total_gets * 100) if total_gets > 0 else 0, 2),
-                "total_puts": self.stats_wrapper.total_puts,
-                "total_deletes": self.stats_wrapper.total_deletes,
+                "total_puts": total_puts,
+                "total_deletes": total_deletes,
             }
         return {}
 

examples/web_scraper_cache/pyproject.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "Web scraper cache using py-key-value with encryption and size limits"
 requires-python = ">=3.10"
 dependencies = [
-    "py-key-value-aio>=0.2.8",
+    "py-key-value-aio[disk,memory]>=0.2.8",
     "pydantic>=2.0.0,<3.0.0",
     "cryptography>=41.0.0",
 ]
@@ -18,6 +18,9 @@ dev = [
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

examples/web_scraper_cache/requirements.txt

@@ -1,3 +1,3 @@
-py-key-value-aio>=0.2.8
+py-key-value-aio[disk,memory]>=0.2.8
 pydantic>=2.0.0,<3.0.0
 cryptography>=41.0.0

examples/web_scraper_cache/scraper.py

@@ -19,7 +19,7 @@
 from key_value.aio.adapters.pydantic import PydanticAdapter
 from key_value.aio.stores.disk.store import DiskStore
 from key_value.aio.stores.memory.store import MemoryStore
-from key_value.aio.wrappers.encryption.wrapper import FernetEncryptionWrapper
+from key_value.aio.wrappers.encryption.fernet import FernetEncryptionWrapper
 from key_value.aio.wrappers.fallback.wrapper import FallbackWrapper
 from key_value.aio.wrappers.limit_size.wrapper import LimitSizeWrapper
 from key_value.aio.wrappers.ttl_clamp.wrapper import TTLClampWrapper
@@ -60,11 +60,14 @@ def __init__(self, cache_dir: str = ".scraper_cache", encryption_key: bytes | No
         self.encryption_key = encryption_key
 
         # Primary store: Disk with encryption and size limits
-        disk_store = DiskStore(root_directory=cache_dir)
+        disk_store = DiskStore(directory=cache_dir)
 
         # Fallback store: Memory (for when disk fails)
         fallback_store = MemoryStore()
 
+        # Create Fernet instance for encryption
+        fernet = Fernet(encryption_key)
+
         # Wrapper stack (applied inside-out):
         # 1. TTLClampWrapper - Enforce cache duration (min 1 hour, max 7 days)
         # 2. LimitSizeWrapper - Prevent huge pages (max 5MB per page)
@@ -73,10 +76,11 @@ def __init__(self, cache_dir: str = ".scraper_cache", encryption_key: bytes | No
         primary_with_wrappers = TTLClampWrapper(
             key_value=LimitSizeWrapper(
                 key_value=FernetEncryptionWrapper(
-                    key_value=FallbackWrapper(key_value=disk_store, fallback=fallback_store),
-                    key=encryption_key,
+                    key_value=FallbackWrapper(primary_key_value=disk_store, fallback_key_value=fallback_store),
+                    fernet=fernet,
+                    raise_on_decryption_error=False,  # Return None on decryption failure instead of raising
                 ),
-                max_size_bytes=5 * 1024 * 1024,  # 5MB limit
+                max_size=5 * 1024 * 1024,  # 5MB limit
             ),
             min_ttl=3600,  # 1 hour minimum
             max_ttl=7 * 24 * 3600,  # 7 days maximum