feat: on-get callback

src/cacheout/cache.py

@@ -74,6 +74,7 @@ class Cache:
         default: Default value or function to use in :meth:`get` when key is not found. If callable,
             it will be passed a single argument, ``key``, and its return value will be set for that
             cache key.
+        on_get: Callback which will be executed when a cache entry is got.
         on_delete: Callback which will be executed when a cache entry is removed.
         stats: Cache statistics.
     """
@@ -90,12 +91,14 @@ def __init__(
         timer: t.Callable[[], T_TTL] = time.time,
         default: t.Any = None,
         enable_stats: bool = False,
+        on_get: t.Optional[t.Callable[[t.Hashable, t.Any, bool], None]] = None,
         on_delete: t.Optional[t.Callable[[t.Hashable, t.Any, RemovalCause], None]] = None,
     ):
         self.maxsize = maxsize
         self.ttl = ttl
         self.timer = timer
         self.default = default
+        self.on_get = on_get
         self.on_delete = on_delete
         self.stats = CacheStatsTracker(self, enable=enable_stats)
 
@@ -262,6 +265,9 @@ def _get(self, key: t.Hashable, default: t.Any = None) -> t.Any:
                 self._delete(key, RemovalCause.EXPIRED)
                 raise KeyError
             self.stats.inc_hit_count()
+
+            if self.on_get:
+                self.on_get(key, value, True)
         except KeyError:
             self.stats.inc_miss_count()
             if default is None:
@@ -273,6 +279,9 @@ def _get(self, key: t.Hashable, default: t.Any = None) -> t.Any:
             else:
                 value = default
 
+            if self.on_get:
+                self.on_get(key, value, False)
+
         return value
 
     def get_many(self, iteratee: T_FILTER) -> dict:

tests/test_cache.py

@@ -719,32 +719,50 @@ def test_cache_on_delete(cache: Cache, timer: Timer):
 
     def on_delete(key, value, cause):
         nonlocal log
-        log = f"{key}:{value} {cause.value}"
+        log = f"{key}={value}, RemovalCause={cause.value}"
 
     cache.on_delete = on_delete
     cache.set("DELETE", 1)
     cache.delete("DELETE")
-    assert log == f"DELETE:1 {RemovalCause.DELETE.value}"
+    assert log == f"DELETE=1, RemovalCause={RemovalCause.DELETE.value}"
 
     cache.set("SET", 1)
     cache.set("SET", 2)
-    assert log == f"SET:1 {RemovalCause.SET.value}"
+    assert log == f"SET=1, RemovalCause={RemovalCause.SET.value}"
 
     cache.clear()
     cache.set("POPITEM", 1)
     cache.popitem()
-    assert log == f"POPITEM:1 {RemovalCause.POPITEM.value}"
+    assert log == f"POPITEM=1, RemovalCause={RemovalCause.POPITEM.value}"
 
     cache.set("EXPIRED", 1, ttl=1)
     timer.time = 1
     cache.delete_expired()
-    assert log == f"EXPIRED:1 {RemovalCause.EXPIRED.value}"
+    assert log == f"EXPIRED=1, RemovalCause={RemovalCause.EXPIRED.value}"
 
     cache.clear()
     cache.maxsize = 1
     cache.set("FULL", 1)
     cache.set("OVERFLOW", 2)
-    assert log == f"FULL:1 {RemovalCause.FULL.value}"
+    assert log == f"FULL=1, RemovalCause={RemovalCause.FULL.value}"
+
+
+def test_cache_on_get(cache: Cache):
+    """Test that on_get(cache) callback."""
+    log = ""
+
+    def on_get(key, value, existed):
+        nonlocal log
+        log = f"{key}={value}, existed={existed}"
+
+    cache.on_get = on_get
+    cache.set("hit", 1)
+
+    cache.get("hit")
+    assert log == "hit=1, existed=True"
+
+    cache.get("miss")
+    assert log == "miss=None, existed=False"
 
 
 def test_cache_stats__disabled_by_default(cache: Cache):