add stats() method

Author: Fabien Coelho

CacheToolsUtils.py

@@ -72,6 +72,9 @@ class _StatsMix:
     def hits(self):
         return self._cache.hits()  # type: ignore
 
+    def stats(self):
+        return self._cache.stats()  # type: ignore
+
     def reset(self):
         return self._cache.reset()  # type: ignore
 
@@ -102,7 +105,7 @@ def dbsize(self, *args, **kwargs):
 # CACHETOOLS EXTENSIONS
 #
 
-class DebugCache(MutableMapping):
+class DebugCache(_StatsMix, MutableMapping):
     """Debug class.
 
     :param cache: actual cache
@@ -243,12 +246,23 @@ def __init__(self, cache: MutableMapping):
 
     def hits(self):
         """Return the cache hit ratio."""
-        return float(self._hits) / float(max(self._reads, 1))
+        return float(self._hits) / max(self._reads, 1)
 
     def reset(self):
         """Reset internal stats data."""
         self._reads, self._writes, self._dels, self._hits = 0, 0, 0, 0
 
+    def stats(self):
+        """Return available stats data as dict."""
+        return {
+            "type": 1,
+            "reads": self._reads,
+            "writes": self._writes,
+            "dels": self._dels,
+            "hits": self.hits(),
+            "size": self._cache.__len__()
+        }
+
     def __getitem__(self, key):
         self._reads += 1
         res = self._cache.__getitem__(key)
@@ -324,6 +338,20 @@ def clear(self):
         # NOTE not passed on cache2…
         return self._cache.clear()
 
+    def stats(self):
+        return {
+            "type": 2,
+            "cache1": self._cache.stats(),  # type: ignore
+            "cache2": self._cache2.stats()  # type: ignore
+        }
+
+    def hits(self):
+        data = self.stats()
+        c1, c2 = data["cache1"], data["cache2"]
+        if c1["type"] == 1 and c2["type"] == 1:
+            return float(c1["hits"] + c2["hits"]) / max(c1["reads"] + c2["reads"], 1)
+        # else None
+
     def reset(self):  # pragma: no cover
         self._cache.reset()  # type: ignore
         self._cache2.reset()  # type: ignore
@@ -484,7 +512,7 @@ def clear(self):  # pragma: no cover
         """Flush MemCached contents."""
         return self._cache.flush_all()  # type: ignore
 
-    def hits(self) -> float:
+    def hits(self):
         """Return overall cache hit ratio."""
         stats = self._cache.stats()  # type: ignore
         return float(stats[b"get_hits"]) / max(stats[b"cmd_get"], 1)
@@ -586,6 +614,9 @@ def info(self, *args, **kwargs):
         """Return redis informations."""
         return self._cache.info(*args, **kwargs)
 
+    def stats(self):
+        return self.info(section="stats")
+
     def dbsize(self, *args, **kwargs):
         """Return redis database size."""
         return self._cache.dbsize(*args, **kwargs)
@@ -608,7 +639,7 @@ def delete(self, index):
     # stats
     def hits(self):
         """Return cache hits."""
-        stats = self.info(section="stats")
+        stats = self.stats()
         return float(stats["keyspace_hits"]) / (
             stats["keyspace_hits"] + stats["keyspace_misses"]
         )

Makefile

@@ -73,8 +73,8 @@ check.pytest: venv
 check.coverage: venv
 	source venv/bin/activate
 	coverage run -m $(PYTEST) $(PYTOPT) test.py
-	coverage html $(MODULE).py
-	coverage report --fail-under=100 --include=CacheToolsUtils.py
+	# coverage html $(MODULE).py
+	coverage report --fail-under=100 --precision=1 --show-missing --include=CacheToolsUtils.py
 
 .PHONY: check.docs
 check.docs: venv

README.md

@@ -31,12 +31,13 @@ with `cachetools`.
   class for Memcached.
 - `DictCache` a very simple `dict` cache.
 
-### Other wrappers to extend cache capabilities
+### Wrappers to extend cache capabilities
 
 - `PrefixedCache`, `PrefixedMemCached` and `PrefixedRedisCache` add a prefix to
   distinguish sources on a shared cache.
-- `StatsCache`, `StatsMemCached` and `StatsRedisCache` add a `hits()` method
-  to report the cache hit rate.
+- `StatsCache`, `MemCached` and `RedisCache` add a `hits` method
+  to report the cache hit rate, `stats` to report statistics and
+  `reset` to reset statistics.
 - `LockedCache` use a (thread) lock to control cache accesses.
 - `TwoLevelCache` allows to combine two caches.
 - `DebugCache` to trace cache calls using `logging`.

docs/VERSIONS.md

@@ -21,6 +21,7 @@ Install [package](https://pypi.org/project/CacheToolsUtils/) from
 
 ## ? on ?
 
+Add `stats` method to return a convenient `dict` of statistics.
 Fix doc typo.
 
 ## 8.6 on 2024-08-03

test.py

@@ -139,6 +139,7 @@ def test_stats_ct():
     assert cache[(4, "a", True)] == 114
     assert cache[(0, None, False)] == -20
     assert cache.hits() > 0.8
+    assert isinstance(cache.stats(), dict)
     cache.clear()
     setgetdel(c0)
     setgetdel(cache)
@@ -189,6 +190,7 @@ def test_stats_memcached():
     assert c1["(1, 'a', True)"] == 111
     assert c1["(3, None, False)"] == -17
     assert c1.hits() > 0.0
+    assert isinstance(c1.stats(), dict)
     setgetdel(c0)
     setgetdel(c1)
 
@@ -247,6 +249,7 @@ def test_stats_redis():
     assert c1[(1, "a", True)] == 111
     assert c1[(3, None, False)] == -17
     assert c1.hits() > 0.0
+    assert isinstance(c1.stats(), dict)
     setgetdel(c1)
 
 
@@ -263,6 +266,7 @@ def test_stacked_redis():
     run_cached(c3)
     assert len(c3) >= 50
     assert c2.hits() > 0.0
+    assert isinstance(c2.stats(), dict)
     setgetdel(c1)
     setgetdel(c2)
     setgetdel(c3)
@@ -280,7 +284,11 @@ def test_two_level_small():
     assert len(c0s) == 50
     assert c0s._reads == c1s._reads
     assert c1s.hits() == 0.0
+    assert isinstance(c1s.stats(), dict)
     assert c0s.hits() > 0.8
+    assert isinstance(c0s.stats(), dict)
+    assert c2.hits() > 0.0
+    assert isinstance(c2.stats(), dict)
     c2.clear()
     setgetdel(c0)
     setgetdel(c1)
@@ -292,7 +300,7 @@ def test_two_level_small():
 def test_two_level_ok():
     # front cache is too small, always fallback
     c0 = ct.LRUCache(200)
-    c1 = ct.MRUCache(100)
+    c1 = ct.LFUCache(100)
     c0s = ctu.StatsCache(c0)
     c1s = ctu.StatsCache(c1)
     c2 = ctu.TwoLevelCache(c1s, c0s)
@@ -304,7 +312,11 @@ def test_two_level_ok():
     assert c0s._writes == 0
     assert c1s._reads == 500
     assert c1s.hits() == 0.9
+    assert isinstance(c1s.stats(), dict)
     assert c0s.hits() == 1.0
+    assert isinstance(c0s.stats(), dict)
+    assert c2.hits() > 0.0
+    assert isinstance(c2.stats(), dict)
     c2.clear()
     setgetdel(c0)
     setgetdel(c1)
@@ -351,6 +363,7 @@ def test_methods():
         n = s.sum_n2(i) + s.sum_n1(i)
     assert len(c) == 259
     assert cs.hits() > 0.6
+    assert isinstance(cs.stats(), dict)
     ctu.cacheMethods(cs, s, sum_n1="x.")
     try:
         ctu.cacheMethods(cs, s, no_such_method="?.")
@@ -374,6 +387,7 @@ def test_functions():
         n = sum_n2(i) + sum_n2(i) + sum_n2(i)
     assert len(c) == 129
     assert cs.hits() > 0.7
+    assert isinstance(cs.stats(), dict)
 
 
 def test_corners():
@@ -463,17 +477,20 @@ def cached(s: str, i: int):
     cached("hello", 4)
     assert cached.cache_in("hello", 4)
     assert cache.hits() == 0.5
+    assert isinstance(cache.stats(), dict)
     cached.cache_del("hello", 4)
     assert not cached.cache_in("hello", 4)
 
 def test_debug():
     log = logging.getLogger("debug-test")
     log.setLevel(logging.DEBUG)
-    cache = ctu.DebugCache(ctu.DictCache(), log, "test_debug")
+    cache = ctu.DebugCache(ctu.StatsCache(ctu.DictCache()), log, "test_debug")
     run_cached(cache)
     cache["Hello"] = "World!"
     assert "Hello" in cache
     assert len(cache) > 0
+    assert cache.hits() > 0.0
+    assert isinstance(cache.stats(), dict)
     has_hello = False
     for k in iter(cache):
         if k == "Hello":