tests

Author: agkloop

CHANGELOG.md

@@ -10,8 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - RedisCache now supports pluggable serializers with built-ins for `pickle` (default) and `json`, plus custom `dumps`/`loads` implementations.
 - `HybridCache.from_redis` helper for a one-liner L1 (in-memory) + L2 (Redis) setup.
+- `HybridCache` now supports `l2_ttl` parameter for independent L2 TTL control. Defaults to `l1_ttl * 2` if not specified.
 - `__version__` attribute exposed in the main module for version checking.
-- Comprehensive test coverage for BGCache lambda cache factory pattern.
+- Comprehensive test coverage for BGCache lambda cache factory pattern and HybridCache l2_ttl behavior.
 - Documentation example for using lambda cache factories with BGCache (lazy Redis connection initialization).
 
 ## [0.1.4] - 2025-12-12

README.md

@@ -157,9 +157,18 @@ from advanced_caching import HybridCache, InMemCache, RedisCache
 
 l1 = InMemCache()
 l2 = RedisCache(client, prefix="app:")
+# l2_ttl defaults to l1_ttl * 2 if not specified
 hybrid = HybridCache(l1_cache=l1, l2_cache=l2, l1_ttl=60)
+
+# Explicit l2_ttl for longer L2 persistence
+hybrid_long_l2 = HybridCache(l1_cache=l1, l2_cache=l2, l1_ttl=60, l2_ttl=3600)
 ```
 
+**TTL behavior:**
+- `l1_ttl`: How long data stays in fast L1 memory cache
+- `l2_ttl`: How long data persists in L2 (Redis). Defaults to `l1_ttl * 2`
+- When data expires from L1 but exists in L2, it's automatically repopulated to L1
+
 #### With BGCache using lambda factory
 
 For lazy initialization (e.g., deferred Redis connection):
@@ -180,7 +189,8 @@ def get_redis_cache():
     cache=lambda: HybridCache(
         l1_cache=InMemCache(),
         l2_cache=get_redis_cache(),
-        l1_ttl=86400
+        l1_ttl=3600,
+        l2_ttl=86400  # L2 persists longer than L1
     )
 )
 def load_config_map() -> dict[str, dict]:
@@ -254,9 +264,9 @@ assert validate_cache_storage(cache)
 * `BGCache.register_loader(key, interval_seconds, ttl=None, run_immediately=True)`
 * Storages:
 
-  * `InMemCache`
-  * `RedisCache`
-  * `HybridCache`
+  * `InMemCache()`
+  * `RedisCache(redis_client, prefix="", serializer="pickle"|"json"|custom)`
+  * `HybridCache(l1_cache, l2_cache, l1_ttl=60, l2_ttl=None)` - `l2_ttl` defaults to `l1_ttl * 2`
 * Utilities:
 
   * `CacheEntry`

src/advanced_caching/storage.py

@@ -478,6 +478,7 @@ def __init__(
         l1_cache: CacheStorage | None = None,
         l2_cache: CacheStorage | None = None,
         l1_ttl: int = 60,
+        l2_ttl: int | None = None,
     ):
         """
         Initialize hybrid cache.
@@ -486,12 +487,14 @@ def __init__(
             l1_cache: L1 cache (memory), defaults to InMemCache
             l2_cache: L2 cache (distributed), required
             l1_ttl: TTL for L1 cache in seconds
+            l2_ttl: TTL for L2 cache in seconds, defaults to l1_ttl * 2
         """
         self.l1 = l1_cache if l1_cache is not None else InMemCache()
         if l2_cache is None:
             raise ValueError("l2_cache is required for HybridCache")
         self.l2 = l2_cache
         self.l1_ttl = l1_ttl
+        self.l2_ttl = l2_ttl if l2_ttl is not None else l1_ttl * 2
 
     def get(self, key: str) -> Any | None:
         """Get value, checking L1 then L2."""
@@ -511,7 +514,8 @@ def get(self, key: str) -> Any | None:
     def set(self, key: str, value: Any, ttl: int = 0) -> None:
         """Set value in both L1 and L2."""
         self.l1.set(key, value, min(ttl, self.l1_ttl) if ttl > 0 else self.l1_ttl)
-        self.l2.set(key, value, ttl)
+        l2_ttl = min(ttl, self.l2_ttl) if ttl > 0 else self.l2_ttl
+        self.l2.set(key, value, l2_ttl)
 
     def get_entry(self, key: str) -> CacheEntry | None:
         """Get raw entry preferring L1, falling back to L2 and repopulating L1."""
@@ -555,19 +559,22 @@ def exists(self, key: str) -> bool:
 
     def set_if_not_exists(self, key: str, value: Any, ttl: int) -> bool:
         """Atomic set if not exists (L2 only for consistency)."""
-        success = self.l2.set_if_not_exists(key, value, ttl)
+        l2_ttl = min(ttl, self.l2_ttl) if ttl > 0 else self.l2_ttl
+        success = self.l2.set_if_not_exists(key, value, l2_ttl)
         if success:
             self.l1.set(key, value, min(ttl, self.l1_ttl) if ttl > 0 else self.l1_ttl)
         return success
 
     def set_entry(self, key: str, entry: CacheEntry, ttl: int | None = None) -> None:
-        """Store raw entry in both layers, respecting L1 TTL."""
+        """Store raw entry in both layers, respecting L1 and L2 TTL."""
         ttl = ttl if ttl is not None else max(int(entry.fresh_until - time.time()), 0)
 
         l1_ttl = min(ttl, self.l1_ttl) if ttl > 0 else self.l1_ttl
+        l2_ttl = min(ttl, self.l2_ttl) if ttl > 0 else self.l2_ttl
+
         self.l1.set_entry(key, entry, ttl=l1_ttl)
 
         if hasattr(self.l2, "set_entry"):
-            self.l2.set_entry(key, entry, ttl=ttl)  # type: ignore[attr-defined]
+            self.l2.set_entry(key, entry, ttl=l2_ttl)  # type: ignore[attr-defined]
         else:
-            self.l2.set(key, entry.value, ttl)
+            self.l2.set(key, entry.value, l2_ttl)

tests/test_correctness.py

@@ -721,6 +721,127 @@ def f(*, x: int) -> int:
         assert calls["n"] == 1
 
 
+class TestHybridCache:
+    """Test HybridCache L1+L2 behavior with l2_ttl."""
+
+    def test_l2_ttl_defaults_to_l1_ttl_times_2(self):
+        """Test that l2_ttl defaults to l1_ttl * 2."""
+        l1 = InMemCache()
+        l2 = InMemCache()
+
+        cache = HybridCache(l1_cache=l1, l2_cache=l2, l1_ttl=60)
+        assert cache.l1_ttl == 60
+        assert cache.l2_ttl == 120
+
+    def test_l2_ttl_explicit_value(self):
+        """Test that explicit l2_ttl is respected."""
+        l1 = InMemCache()
+        l2 = InMemCache()
+
+        cache = HybridCache(l1_cache=l1, l2_cache=l2, l1_ttl=60, l2_ttl=300)
+        assert cache.l1_ttl == 60
+        assert cache.l2_ttl == 300
+
+    def test_set_respects_l2_ttl(self):
+        """Test that set() uses l2_ttl for L2 cache."""
+        l1 = InMemCache()
+        l2 = InMemCache()
+
+        # Set l1_ttl=1, l2_ttl=10
+        cache = HybridCache(l1_cache=l1, l2_cache=l2, l1_ttl=1, l2_ttl=10)
+
+        cache.set("key1", "value1", ttl=100)
+
+        # Both should have the value immediately
+        assert cache.get("key1") == "value1"
+        assert l1.get("key1") == "value1"
+        assert l2.get("key1") == "value1"
+
+        # Wait for L1 to expire (l1_ttl=1)
+        time.sleep(1.2)
+
+        # L1 should be expired, but L2 should still have it
+        assert l1.get("key1") is None
+        assert l2.get("key1") == "value1"
+
+        # HybridCache should fetch from L2 and repopulate L1
+        assert cache.get("key1") == "value1"
+        assert l1.get("key1") == "value1"  # L1 repopulated
+
+    def test_set_entry_respects_l2_ttl(self):
+        """Test that set_entry() uses l2_ttl for L2 cache."""
+        from advanced_caching.storage import CacheEntry
+
+        l1 = InMemCache()
+        l2 = InMemCache()
+
+        cache = HybridCache(l1_cache=l1, l2_cache=l2, l1_ttl=1, l2_ttl=10)
+
+        now = time.time()
+        entry = CacheEntry(value="test_value", fresh_until=now + 100, created_at=now)
+
+        cache.set_entry("key2", entry, ttl=100)
+
+        # Both should have the entry (using get() which checks freshness)
+        assert cache.get("key2") == "test_value"
+        assert l1.get("key2") == "test_value"
+        assert l2.get("key2") == "test_value"
+
+        # Wait for L1 to expire (l1_ttl=1)
+        time.sleep(1.2)
+
+        # L1 expired (get() returns None for expired), L2 should still have it
+        assert l1.get("key2") is None
+        assert l2.get("key2") == "test_value"
+
+        # HybridCache should fetch from L2
+        assert cache.get("key2") == "test_value"
+
+    def test_set_if_not_exists_respects_l2_ttl(self):
+        """Test that set_if_not_exists() uses l2_ttl for L2 cache."""
+        l1 = InMemCache()
+        l2 = InMemCache()
+
+        cache = HybridCache(l1_cache=l1, l2_cache=l2, l1_ttl=1, l2_ttl=10)
+
+        # First set should succeed
+        assert cache.set_if_not_exists("key3", "value3", ttl=100) is True
+        assert cache.get("key3") == "value3"
+
+        # Second set should fail (key exists)
+        assert cache.set_if_not_exists("key3", "value3_new", ttl=100) is False
+        assert cache.get("key3") == "value3"
+
+        # Wait for L1 to expire
+        time.sleep(1.2)
+
+        # L2 should still have it, so set_if_not_exists should fail
+        assert cache.set_if_not_exists("key3", "value3_new", ttl=100) is False
+
+        # Value should still be original from L2
+        assert cache.get("key3") == "value3"
+
+    def test_l2_ttl_with_zero_ttl_in_set(self):
+        """Test that l2_ttl is used when ttl=0 is passed to set()."""
+        l1 = InMemCache()
+        l2 = InMemCache()
+
+        cache = HybridCache(l1_cache=l1, l2_cache=l2, l1_ttl=2, l2_ttl=5)
+
+        # Set with ttl=0 should use l1_ttl and l2_ttl defaults
+        cache.set("key4", "value4", ttl=0)
+
+        assert cache.get("key4") == "value4"
+
+        # Wait for L1 to expire
+        time.sleep(2.2)
+
+        # L1 expired, but L2 should still have it (l2_ttl=5)
+        assert l1.get("key4") is None
+        assert l2.get("key4") == "value4"
+        assert cache.get("key4") == "value4"
+
+
 class TestNoCachingWhenZero:
     """Ensure ttl/interval_seconds == 0 disables caching/background behavior."""