CacheToolsUtils 8.3__tar.gz → 8.5__tar.gz

{CacheToolsUtils-8.3 → CacheToolsUtils-8.5}/CacheToolsUtils.egg-info/PKG-INFO

@@ -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.3 → CacheToolsUtils-8.5}/CacheToolsUtils.egg-info/requires.txt

@@ -2,6 +2,7 @@ cachetools
 
 [dev]
 mypy
+pyright
 black
 flake8
 pytest

{CacheToolsUtils-8.3 → CacheToolsUtils-8.5}/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 → CacheToolsUtils-8.5}/PKG-INFO

@@ -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.3 → CacheToolsUtils-8.5}/README.md

@@ -9,9 +9,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
@@ -28,7 +29,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
 
@@ -42,7 +43,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.3 → CacheToolsUtils-8.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "CacheToolsUtils"
-version = "8.3"
+version = "8.5"
 authors = [ { name = "Fabien Coelho", email = "cachetools.utils@coelho.net" } ]
 description = "Cachetools Utilities"
 readme = "README.md"
@@ -30,7 +30,7 @@ package = "https://pypi.org/project/CacheToolsUtils/"
 py-modules = [ "CacheToolsUtils" ]
 
 [project.optional-dependencies]
-dev = [ "mypy", "black", "flake8", "pytest", "coverage", "pymarkdownlnt", "types-redis", "types-cachetools" ]
+dev = [ "mypy", "pyright", "black", "flake8", "pytest", "coverage", "pymarkdownlnt", "types-redis", "types-cachetools" ]
 doc = [ "sphinx", "sphinx_rtd_theme", "sphinx-autoapi", "sphinx-lint", "myst_parser" ]
 tests = [ "pymemcache", "redis" ]
 pub = [ "build", "wheel", "twine" ]