type declarations

Author: Fabien Coelho

CacheToolsUtils.py

@@ -69,10 +69,10 @@ def __delitem__(self, key: Any):
 class _StatsMix:
     """Convenient Mixin to forward stats methods to _cache."""
 
-    def hits(self):
+    def hits(self) -> float|None:
         return self._cache.hits()  # type: ignore
 
-    def stats(self):
+    def stats(self) -> dict[str, Any]:
         return self._cache.stats()  # type: ignore
 
     def reset(self):
@@ -244,15 +244,15 @@ def __init__(self, cache: MutableMapping):
         self._cache = cache
         self.reset()
 
-    def hits(self):
+    def hits(self) -> float:
         """Return the cache hit ratio."""
         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):
+    def stats(self) -> dict[str, Any]:
         """Return available stats data as dict."""
         return {
             "type": 1,
@@ -338,17 +338,23 @@ 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 stats(self) -> dict[str, Any]:
+        data = { "type": 2 }
+        try:
+            data["cache1"] = self._cache.stats()  # type: ignore
+        except Exception:
+            data["cache1"] = {}  # type: ignore
+        try:
+            data["cache2"] = self._cache2.stats()  # type: ignore
+        except Exception:
+            data["cache2"] = {}  # type: ignore
+        return data
 
-    def hits(self):
+    def hits(self) -> float|None:
         data = self.stats()
         c1, c2 = data["cache1"], data["cache2"]
-        if c1["type"] == 1 and c2["type"] == 1:
+        if (c1 and "type" in c1 and c1["type"] == 1 and
+            c2 and "type" in c2 and c2["type"] == 1):
             return float(c1["hits"] + c2["hits"]) / max(c1["reads"] + c2["reads"], 1)
         # else None
 
@@ -512,7 +518,7 @@ def clear(self):  # pragma: no cover
         """Flush MemCached contents."""
         return self._cache.flush_all()  # type: ignore
 
-    def hits(self):
+    def hits(self) -> float:
         """Return overall cache hit ratio."""
         stats = self._cache.stats()  # type: ignore
         return float(stats[b"get_hits"]) / max(stats[b"cmd_get"], 1)
@@ -614,7 +620,7 @@ def info(self, *args, **kwargs):
         """Return redis informations."""
         return self._cache.info(*args, **kwargs)
 
-    def stats(self):
+    def stats(self) -> dict[str, Any]:
         return self.info(section="stats")
 
     def dbsize(self, *args, **kwargs):
@@ -637,7 +643,7 @@ def delete(self, index):
         del self[index]
 
     # stats
-    def hits(self):
+    def hits(self) -> float:
         """Return cache hits."""
         stats = self.stats()
         return float(stats["keyspace_hits"]) / (

README.md

@@ -7,7 +7,7 @@ Classes to add key prefix and stats to
 and other cache-related utils.
 
 ![Status](https://github.com/zx80/cachetools-utils/actions/workflows/cachetools-utils.yml/badge.svg?branch=main&style=flat)
-![Tests](https://img.shields.io/badge/tests-17%20✓-success)
+![Tests](https://img.shields.io/badge/tests-19%20✓-success)
 ![Coverage](https://img.shields.io/badge/coverage-100%25-success)
 ![Issues](https://img.shields.io/github/issues/zx80/cachetools-utils?style=flat)
 ![Python](https://img.shields.io/badge/python-3-informational)

docs/VERSIONS.md

@@ -19,9 +19,12 @@ Install [package](https://pypi.org/project/CacheToolsUtils/) from
   Maybe the existing client can do that with appropriate options?
 - `cached`: add `contains` and `delete` parameters to change names?
 
-## ? on ?
+## 9.0 on ?
 
 Add `stats` method to return a convenient `dict` of statistics.
+Improve type declarations.
+Add some tests.
+Test with (future) Python 3.14.
 Fix doc typo.
 
 ## 8.6 on 2024-08-03

test.py

@@ -329,6 +329,14 @@ def test_two_level_ok():
     del c2[KEY]
 
 
+def test_twolevel_bad_stats():
+    c0 = ctu.DictCache()
+    c1 = ctu.DictCache()
+    c2 = ctu.TwoLevelCache(c0, c1)
+    assert isinstance(c2.stats(), dict)
+    assert c2.hits() is None
+
+
 class Stuff:
     """Test class with cacheable methods."""