CacheToolsUtils 8.6__py3-none-any.whl → 9.1__py3-none-any.whl

{CacheToolsUtils-8.6.dist-info → CacheToolsUtils-9.1.dist-info}/METADATA

@@ -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
@@ -18,29 +18,29 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cachetools
 Provides-Extra: dev
-Requires-Dist: mypy ; extra == 'dev'
-Requires-Dist: pyright ; extra == 'dev'
-Requires-Dist: black ; extra == 'dev'
-Requires-Dist: flake8 ; extra == 'dev'
-Requires-Dist: ruff ; extra == 'dev'
-Requires-Dist: pytest ; extra == 'dev'
-Requires-Dist: coverage ; extra == 'dev'
-Requires-Dist: pymarkdownlnt ; extra == 'dev'
-Requires-Dist: types-redis ; extra == 'dev'
-Requires-Dist: types-cachetools ; extra == 'dev'
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: pymarkdownlnt; extra == "dev"
+Requires-Dist: types-redis; extra == "dev"
+Requires-Dist: types-cachetools; extra == "dev"
 Provides-Extra: doc
-Requires-Dist: sphinx ; extra == 'doc'
-Requires-Dist: sphinx-rtd-theme ; extra == 'doc'
-Requires-Dist: sphinx-autoapi ; extra == 'doc'
-Requires-Dist: sphinx-lint ; extra == 'doc'
-Requires-Dist: myst-parser ; extra == 'doc'
-Provides-Extra: pub
-Requires-Dist: build ; extra == 'pub'
-Requires-Dist: wheel ; extra == 'pub'
-Requires-Dist: twine ; extra == 'pub'
+Requires-Dist: sphinx; extra == "doc"
+Requires-Dist: sphinx_rtd_theme; extra == "doc"
+Requires-Dist: sphinx-autoapi; extra == "doc"
+Requires-Dist: sphinx-lint; extra == "doc"
+Requires-Dist: myst_parser; extra == "doc"
 Provides-Extra: tests
-Requires-Dist: pymemcache ; extra == 'tests'
-Requires-Dist: redis ; extra == 'tests'
+Requires-Dist: pymemcache; extra == "tests"
+Requires-Dist: redis; extra == "tests"
+Provides-Extra: pub
+Requires-Dist: build; extra == "pub"
+Requires-Dist: wheel; extra == "pub"
+Requires-Dist: twine; extra == "pub"
 
 # CacheToolsUtils
 
@@ -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-9.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+CacheToolsUtils.py,sha256=zLX8cK3Siev3cCx4yOYSEW4hzrfZ9p3ho86_TfXppSY,20248
+CacheToolsUtils-9.1.dist-info/LICENSE,sha256=y_yFW1bmBAUFCF-ZDyDiq10Ykns_19If5pFnZUzYgeU,33
+CacheToolsUtils-9.1.dist-info/METADATA,sha256=60_gOx6frAF770fHQb0RPmS9bBAX5fkKRHuZbb1e6iY,4483
+CacheToolsUtils-9.1.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+CacheToolsUtils-9.1.dist-info/top_level.txt,sha256=qCyE4jGot5mOmvIQrZueCnPtbYtRe2hqke4sGojm3zI,16
+CacheToolsUtils-9.1.dist-info/RECORD,,

{CacheToolsUtils-8.6.dist-info → CacheToolsUtils-9.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (72.1.0)
+Generator: setuptools (75.6.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

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.dist-info/RECORD

@@ -1,6 +0,0 @@
-CacheToolsUtils.py,sha256=kqZNczVcgP_F8oioXBDCqEA5Ux9FovbO_VhlJ67pjiE,18135
-CacheToolsUtils-8.6.dist-info/LICENSE,sha256=y_yFW1bmBAUFCF-ZDyDiq10Ykns_19If5pFnZUzYgeU,33
-CacheToolsUtils-8.6.dist-info/METADATA,sha256=8L90Zezt3-y8LPTq4zHB8TIbjKvV0urezYd5LroZAJ4,4378
-CacheToolsUtils-8.6.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
-CacheToolsUtils-8.6.dist-info/top_level.txt,sha256=qCyE4jGot5mOmvIQrZueCnPtbYtRe2hqke4sGojm3zI,16
-CacheToolsUtils-8.6.dist-info/RECORD,,