CacheToolsUtils 8.6__tar.gz → 9.1__tar.gz

{cachetoolsutils-8.6 → cachetoolsutils-9.1}/CacheToolsUtils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CacheToolsUtils
-Version: 8.6
+Version: 9.1
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -51,7 +51,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-21%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)
@@ -75,12 +75,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`.
@@ -90,6 +91,7 @@ with `cachetools`.
 - `cached` decorator: a cachetools replacement which allows to test if a
   function result is in cache, and to delete such an entry.
 - `cacheFunctions` and `cacheMethods`: add caching to functions or methods.
+- `json_key` and `hash_json_key`: JSON-based cache key serialization functions
 
 ## License
 

{cachetoolsutils-8.6 → cachetoolsutils-9.1}/CacheToolsUtils.py

@@ -25,7 +25,8 @@ _NO_DEFAULT = object()
 class _MutMapMix:
     """Convenient MutableMapping Mixin, forward to _cache."""
 
-    _cache: MutableMapping
+    # FIXME coverage reports this as missing with Python 3.14
+    _cache: MutableMapping  # pragma: no cover
 
     def __contains__(self, key):
         return self._cache.__contains__(key)
@@ -69,9 +70,12 @@ class _KeyMutMapMix(_MutMapMix):
 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) -> dict[str, Any]:
+        return self._cache.stats()  # type: ignore
+
     def reset(self):
         return self._cache.reset()  # type: ignore
 
@@ -102,7 +106,7 @@ class _RedisMix:  # pragma: no cover
 # CACHETOOLS EXTENSIONS
 #
 
-class DebugCache(MutableMapping):
+class DebugCache(_StatsMix, MutableMapping):
     """Debug class.
 
     :param cache: actual cache
@@ -241,14 +245,25 @@ class StatsCache(_MutMapMix, MutableMapping):
         self._cache = cache
         self.reset()
 
-    def hits(self):
+    def hits(self) -> float:
         """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) -> dict[str, Any]:
+        """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 +339,27 @@ class TwoLevelCache(_MutMapMix, MutableMapping):
         # NOTE not passed on cache2…
         return self._cache.clear()
 
+    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) -> float|None:
+        data = self.stats()
+        c1, c2 = data["cache1"], data["cache2"]
+        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
+        return None
+
     def reset(self):  # pragma: no cover
         self._cache.reset()  # type: ignore
         self._cache2.reset()  # type: ignore
@@ -415,6 +451,38 @@ def cacheFunctions(
         globs[fun] = cached(cache=gen(cache, prefix))(f)
 
 
+# JSON-based key function
+# NOTE obviously this only works if parameters are json-serializable…
+def json_key(*args, **kwargs):
+    if kwargs:
+        return json.dumps({"*": args, "**": kwargs}, sort_keys=True)
+    else:  # array
+        return json.dumps(args)
+
+
+# Hmmm…
+class _HashJsonKey:
+    """A cache key with a persistant hash value."""
+
+    def __init__(self, *args, **kwargs):
+        self._hashed = None
+        self._args = args
+        self._kwargs = kwargs
+        self._key = json_key(*args, **kwargs)
+
+    def __hash__(self):
+        if self._hashed is None:
+            self._hashed = self._key.__hash__()
+        return self._hashed
+
+    def __str__(self):
+        return self._key
+
+
+def hash_json_key(*args, **kwargs):
+    return _HashJsonKey(*args, **kwargs)
+
+
 #
 # MEMCACHED
 #
@@ -586,6 +654,9 @@ class RedisCache(MutableMapping):
         """Return redis informations."""
         return self._cache.info(*args, **kwargs)
 
+    def stats(self) -> dict[str, Any]:
+        return self.info(section="stats")
+
     def dbsize(self, *args, **kwargs):
         """Return redis database size."""
         return self._cache.dbsize(*args, **kwargs)
@@ -606,9 +677,9 @@ class RedisCache(MutableMapping):
         del self[index]
 
     # stats
-    def hits(self):
+    def hits(self) -> float:
         """Return cache hits."""
-        stats = self.info(section="stats")
+        stats = self.stats()
         return float(stats["keyspace_hits"]) / (
             stats["keyspace_hits"] + stats["keyspace_misses"]
         )

{cachetoolsutils-8.6 → cachetoolsutils-9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CacheToolsUtils
-Version: 8.6
+Version: 9.1
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -51,7 +51,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-21%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)
@@ -75,12 +75,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`.
@@ -90,6 +91,7 @@ with `cachetools`.
 - `cached` decorator: a cachetools replacement which allows to test if a
   function result is in cache, and to delete such an entry.
 - `cacheFunctions` and `cacheMethods`: add caching to functions or methods.
+- `json_key` and `hash_json_key`: JSON-based cache key serialization functions
 
 ## License
 

{cachetoolsutils-8.6 → cachetoolsutils-9.1}/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-21%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)
@@ -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`.
@@ -46,6 +47,7 @@ with `cachetools`.
 - `cached` decorator: a cachetools replacement which allows to test if a
   function result is in cache, and to delete such an entry.
 - `cacheFunctions` and `cacheMethods`: add caching to functions or methods.
+- `json_key` and `hash_json_key`: JSON-based cache key serialization functions
 
 ## License
 

{cachetoolsutils-8.6 → cachetoolsutils-9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "CacheToolsUtils"
-version = "8.6"
+version = "9.1"
 authors = [ { name = "Fabien Coelho", email = "cachetools.utils@coelho.net" } ]
 description = "Cachetools Utilities"
 readme = "README.md"