CacheToolsUtils 8.3__py3-none-any.whl → 8.5__py3-none-any.whl

{CacheToolsUtils-8.3.dist-info → CacheToolsUtils-8.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CacheToolsUtils
-Version: 8.3
+Version: 8.5
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -19,6 +19,7 @@ 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: pytest ; extra == 'dev'
@@ -51,9 +52,10 @@ 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)
 ![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)
 ![Version](https://img.shields.io/pypi/v/CacheToolsUtils)
-![Badges](https://img.shields.io/badge/badges-7-informational)
+![Badges](https://img.shields.io/badge/badges-8-informational)
 ![License](https://img.shields.io/pypi/l/cachetoolsutils?style=flat)
 
 ## Module Contents
@@ -70,7 +72,7 @@ with `cachetools`.
 - `MemCached` does the same for a Memcached server.
   The utility class `JsonSerde` is a convenient JSON serializer-deserializer
   class for Memcached.
-- `DictCache` a `dict` cache.
+- `DictCache` a very simple `dict` cache.
 
 ### Other wrappers to extend cache capabilities
 
@@ -84,7 +86,7 @@ with `cachetools`.
 
 ### Cache utilities
 
-- `cached` decorator: a cachetools replacement which allows to test e if a
+- `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.
 

CacheToolsUtils-8.5.dist-info/RECORD

@@ -0,0 +1,6 @@
+CacheToolsUtils.py,sha256=kqZNczVcgP_F8oioXBDCqEA5Ux9FovbO_VhlJ67pjiE,18135
+CacheToolsUtils-8.5.dist-info/LICENSE,sha256=y_yFW1bmBAUFCF-ZDyDiq10Ykns_19If5pFnZUzYgeU,33
+CacheToolsUtils-8.5.dist-info/METADATA,sha256=MEAFq8ImCNmiSk49N5yWM3uZCBfHrOLmkQ5b5yVacho,4110
+CacheToolsUtils-8.5.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+CacheToolsUtils-8.5.dist-info/top_level.txt,sha256=qCyE4jGot5mOmvIQrZueCnPtbYtRe2hqke4sGojm3zI,16
+CacheToolsUtils-8.5.dist-info/RECORD,,

{CacheToolsUtils-8.3.dist-info → CacheToolsUtils-8.5.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.3)
+Generator: bdist_wheel (0.42.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

CacheToolsUtils.py

@@ -2,7 +2,8 @@
 CacheTools Utilities. This code is public domain.
 """
 
-from typing import Any, Callable, MutableMapping as MutMap
+from typing import Any, Callable, MutableMapping
+import abc
 
 import cachetools
 import json
@@ -15,7 +16,7 @@ log = logging.getLogger(__name__)
 
 
 #
-# UTILS
+# UTILS: Abstract Classes and Mixins
 #
 
 _NO_DEFAULT = object()
@@ -24,6 +25,8 @@ _NO_DEFAULT = object()
 class _MutMapMix:
     """Convenient MutableMapping Mixin, forward to _cache."""
 
+    _cache: MutableMapping
+
     def __contains__(self, key):
         return self._cache.__contains__(key)
 
@@ -46,16 +49,20 @@ class _MutMapMix:
 class _KeyMutMapMix(_MutMapMix):
     """Convenient MutableMapping Mixin with a key filter, forward to _cache."""
 
-    def __contains__(self, key):
+    @abc.abstractmethod
+    def _key(self, key: Any) -> Any:  # pragma: no cover
+        return None
+
+    def __contains__(self, key: Any):
         return self._cache.__contains__(self._key(key))
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: Any):
         return self._cache.__getitem__(self._key(key))
 
-    def __setitem__(self, key, val):
+    def __setitem__(self, key: Any, val: Any):
         return self._cache.__setitem__(self._key(key), val)
 
-    def __delitem__(self, key):
+    def __delitem__(self, key: Any):
         return self._cache.__delitem__(self._key(key))
 
 
@@ -63,36 +70,39 @@ class _StatsMix:
     """Convenient Mixin to forward stats methods to _cache."""
 
     def hits(self):
-        return self._cache.hits()
+        return self._cache.hits()  # type: ignore
 
     def reset(self):
-        return self._cache.reset()
+        return self._cache.reset()  # type: ignore
 
 
 class _RedisMix:  # pragma: no cover
     """Convenient mixin to forward redis methods."""
 
+    # NOTE declaring _cache would conflict with _MutMapMix
+    # probably there is a clever way to do that, let us not bother
+
     def set(self, *args, **kwargs):
-        return self._cache.set(*args, **kwargs)
+        return self._cache.set(*args, **kwargs)  # type: ignore
 
     def get(self, *args, **kwargs):
-        return self._cache.get(*args, **kwargs)
+        return self._cache.get(*args, **kwargs)  # type: ignore
 
     def delete(self, *args, **kwargs):
-        return self._cache.delete(*args, **kwargs)
+        return self._cache.delete(*args, **kwargs)  # type: ignore
 
     def info(self, *args, **kwargs):
-        return self._cache.info(*args, **kwargs)
+        return self._cache.info(*args, **kwargs)  # type: ignore
 
     def dbsize(self, *args, **kwargs):
-        return self._cache.dbsize(*args, **kwargs)
+        return self._cache.dbsize(*args, **kwargs)  # type: ignore
+
 
 #
 # CACHETOOLS EXTENSIONS
 #
 
-
-class DebugCache:
+class DebugCache(MutableMapping):
     """Debug class.
 
     :param cache: actual cache
@@ -100,7 +110,7 @@ class DebugCache:
     :param name: name of instance for output
     """
 
-    def __init__(self, cache, log, name="cache"):
+    def __init__(self, cache: MutableMapping, log: logging.Logger, name="cache"):
         self._cache = cache
         self._log = log
         self._name = name
@@ -139,10 +149,10 @@ class DebugCache:
 
     def reset(self):  # pragma: no cover
         self._debug("reset")
-        return self._cache.reset()
+        return self._cache.reset()  # type: ignore
 
 
-class DictCache(_MutMapMix):
+class DictCache(_MutMapMix, MutableMapping):
     """Cache class based on dict."""
 
     def __init__(self):
@@ -152,7 +162,7 @@ class DictCache(_MutMapMix):
         self._cache.clear()
 
 
-class LockedCache(_MutMapMix, _StatsMix, _RedisMix, MutMap):
+class LockedCache(_MutMapMix, _StatsMix, _RedisMix, MutableMapping):
     """Cache class with a lock.
 
     :param cache: actual cache.
@@ -168,7 +178,7 @@ class LockedCache(_MutMapMix, _StatsMix, _RedisMix, MutMap):
        cache = ctu.LockedCache(ct.LFUCache(), threading.RLock())
     """
 
-    def __init__(self, cache: MutMap, lock):
+    def __init__(self, cache: MutableMapping, lock):
         self._cache = cache
         self._lock = lock
 
@@ -189,22 +199,28 @@ class LockedCache(_MutMapMix, _StatsMix, _RedisMix, MutMap):
             return self._cache.__delitem__(key)
 
 
-class PrefixedCache(_KeyMutMapMix, _StatsMix, MutMap):
+class PrefixedCache(_KeyMutMapMix, _StatsMix, MutableMapping):
     """Cache class to add a key prefix.
 
     :param cache: actual cache.
     :param prefix: prefix to prepend to keys.
     """
 
-    def __init__(self, cache: MutMap, prefix: str|bytes = ""):
+    def __init__(self, cache: MutableMapping, prefix: str|bytes = ""):
         self._prefix = prefix
         self._cache = cache
+        # dynamic cast
+        self._cast: Callable[[Any], str]|Callable[[Any], bytes]
+        if isinstance(prefix, str):
+            self._cast = lambda v: str(v)
+        else:  # pragma: no cover
+            self._cast = lambda v: bytes(v)
 
-    def _key(self, key):
-        return self._prefix + str(key)
+    def _key(self, key: Any) -> Any:
+        return self._prefix + self._cast(key)  # type: ignore
 
 
-class StatsCache(_MutMapMix, MutMap):
+class StatsCache(_MutMapMix, MutableMapping):
     """Cache class to keep stats.
 
     :param cache: actual cache.
@@ -221,7 +237,7 @@ class StatsCache(_MutMapMix, MutMap):
     However, this only works for its own classes.
     """
 
-    def __init__(self, cache: MutMap):
+    def __init__(self, cache: MutableMapping):
         self._cache = cache
         self.reset()
 
@@ -251,7 +267,7 @@ class StatsCache(_MutMapMix, MutMap):
         return self._cache.clear()
 
 
-class TwoLevelCache(_MutMapMix, MutMap):
+class TwoLevelCache(_MutMapMix, MutableMapping):
     """Two-Level Cache class for CacheTools.
 
     :param cache: first (smaller, shorter TTL) cache
@@ -259,7 +275,7 @@ class TwoLevelCache(_MutMapMix, MutMap):
     :param resilient: whether to ignore cache2 failures
     """
 
-    def __init__(self, cache: MutMap, cache2: MutMap, resilient=False):
+    def __init__(self, cache: MutableMapping, cache2: MutableMapping, resilient=False):
         self._resilient = resilient
         self._cache = cache
         self._cache2 = cache2
@@ -309,8 +325,8 @@ class TwoLevelCache(_MutMapMix, MutMap):
         return self._cache.clear()
 
     def reset(self):  # pragma: no cover
-        self._cache.reset()
-        self._cache2.reset()
+        self._cache.reset()  # type: ignore
+        self._cache2.reset()  # type: ignore
 
 
 def cached(cache, *args, **kwargs):
@@ -332,17 +348,17 @@ def cached(cache, *args, **kwargs):
         fun = cachetools.cached(cache, *args, **kwargs)(fun)
 
         # extend
-        def cache_in(*args, **kwargs):
+        def cache_in(*args, **kwargs) -> bool:
             """Tell whether key is already in cache."""
-            key = fun.cache_key(*args, **kwargs)
-            return key in fun.cache
+            key = fun.cache_key(*args, **kwargs)  # type: ignore
+            return key in fun.cache  # type: ignore
 
         def cache_del(*args, **kwargs):
             """Delete key from cache, return if it was there."""
-            key = fun.cache_key(*args, **kwargs)
-            key_in = key in fun.cache
+            key = fun.cache_key(*args, **kwargs)  # type: ignore
+            key_in = key in fun.cache  # type: ignore
             if key_in:
-                del fun.cache[key]
+                del fun.cache[key]  # type: ignore
             return key_in
 
         fun.cache_in = cache_in    # type: ignore
@@ -354,10 +370,10 @@ def cached(cache, *args, **kwargs):
 
 
 # short generator type name
-MapGen = Callable[[MutMap, str], MutMap]
+MapGen = Callable[[MutableMapping, str], MutableMapping]
 
 
-def cacheMethods(cache: MutMap, obj: Any, gen: MapGen = PrefixedCache, **funs):
+def cacheMethods(cache: MutableMapping, obj: Any, gen: MapGen = PrefixedCache, **funs):
     """Cache some object methods.
 
     :param cache: cache to use.
@@ -378,7 +394,7 @@ def cacheMethods(cache: MutMap, obj: Any, gen: MapGen = PrefixedCache, **funs):
 
 
 def cacheFunctions(
-    cache: MutMap, globs: MutMap[str, Any], gen: MapGen = PrefixedCache, **funs
+    cache: MutableMapping, globs: MutableMapping[str, Any], gen: MapGen = PrefixedCache, **funs
 ):
     """Cache some global functions, with a prefix.
 
@@ -429,7 +445,7 @@ class JsonSerde:
             raise Exception("Unknown serialization format")
 
 
-class MemCached(_KeyMutMapMix, MutMap):
+class MemCached(_KeyMutMapMix, MutableMapping):
     """MemCached-compatible wrapper class for cachetools with key encoding.
 
     :param cache: actual memcached cache.
@@ -451,26 +467,26 @@ class MemCached(_KeyMutMapMix, MutMap):
 
     # memcached keys are constrained bytes, we need some encoding…
     # short (250 bytes) ASCII without control chars nor spaces
-    # we do not use hashing which might be costly and induce collisions
+    # we do not use hashing which might be costly or induce collisions
     def _key(self, key):
         import base64
 
         return base64.b85encode(str(key).encode("utf-8"))
 
     def __len__(self):
-        return self._cache.stats()[b"curr_items"]
+        return self._cache.stats()[b"curr_items"]  # type: ignore
 
-    def stats(self):
+    def stats(self) -> dict[str, Any]:
         """Return MemCached stats."""
-        return self._cache.stats()
+        return self._cache.stats()  # type: ignore
 
     def clear(self):  # pragma: no cover
         """Flush MemCached contents."""
-        return self._cache.flush_all()
+        return self._cache.flush_all()  # type: ignore
 
-    def hits(self):
+    def hits(self) -> float:
         """Return overall cache hit ratio."""
-        stats = self._cache.stats()
+        stats = self._cache.stats()  # type: ignore
         return float(stats[b"get_hits"]) / max(stats[b"cmd_get"], 1)
 
 
@@ -512,7 +528,7 @@ class StatsMemCached(MemCached):
 #
 
 
-class RedisCache(MutMap):
+class RedisCache(MutableMapping):
     """Redis TTL-ed wrapper for cachetools (``redis``).
 
     :param cache: actual redis cache.

CacheToolsUtils-8.3.dist-info/RECORD

@@ -1,6 +0,0 @@
-CacheToolsUtils.py,sha256=0_ftipxNt0SOtA4EJThnoX8M7ma1QS3huxKLb9MQcDM,17015
-CacheToolsUtils-8.3.dist-info/LICENSE,sha256=y_yFW1bmBAUFCF-ZDyDiq10Ykns_19If5pFnZUzYgeU,33
-CacheToolsUtils-8.3.dist-info/METADATA,sha256=XhGZ8w4A7MDcitjZE3lJ2NPr88R_j5ysatzqCfHer58,3979
-CacheToolsUtils-8.3.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
-CacheToolsUtils-8.3.dist-info/top_level.txt,sha256=qCyE4jGot5mOmvIQrZueCnPtbYtRe2hqke4sGojm3zI,16
-CacheToolsUtils-8.3.dist-info/RECORD,,