CacheToolsUtils 10.3__tar.gz → 11.0__tar.gz

{cachetoolsutils-10.3 → cachetoolsutils-11.0}/CacheToolsUtils.egg-info/PKG-INFO

@@ -1,16 +1,15 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: CacheToolsUtils
-Version: 10.3
+Version: 11.0
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
-License: CC0
+License-Expression: CC0-1.0
 Project-URL: repository, https://github.com/zx80/cachetools-utils
 Project-URL: documentation, https://zx80.github.io/cachetools-utils/
 Project-URL: issues, https://github.com/zx80/cachetools-utils/issues
 Project-URL: package, https://pypi.org/project/CacheToolsUtils/
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
 Classifier: Programming Language :: Python
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
@@ -26,14 +25,10 @@ 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"
+Requires-Dist: mkdocs; extra == "doc"
+Requires-Dist: mkdocs-material; extra == "doc"
+Requires-Dist: mkdocstrings[python]; extra == "doc"
 Provides-Extra: crypt
 Requires-Dist: pycryptodome; extra == "crypt"
 Provides-Extra: tests
@@ -43,17 +38,16 @@ Provides-Extra: pub
 Requires-Dist: build; extra == "pub"
 Requires-Dist: wheel; extra == "pub"
 Requires-Dist: twine; extra == "pub"
+Dynamic: license-file
 
 # CacheToolsUtils
 
-Classes to add key prefix and stats to
-[cachetools](https://pypi.org/project/cachetools/) classes and use
-[redis](https://redis.io/) and
-[memcached](https://memcached.org/) as storage backends,
-and other cache-related utils.
+Stackable cache classes for sharing, encryption, statistics _and more_
+on top of [cachetools](https://pypi.org/project/cachetools/),
+[redis](https://redis.io/) and [memcached](https://memcached.org/).
 
-![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-23%20✓-success)
+![Status](https://github.com/zx80/cachetools-utils/actions/workflows/ctu.yml/badge.svg?branch=main&style=flat)
+![Tests](https://img.shields.io/badge/tests-25%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)
@@ -66,7 +60,37 @@ and other cache-related utils.
 For our purpose, a cache is a key-value store, aka a dictionary, possibly with
 some constraints on keys (type, size) and values (size, serialization).
 This module provides new caches, wrappers and other utilities suitable to use
-with `cachetools`.
+with `cachetools`. Example:
+
+```python
+import redis
+import CacheToolsUtils as ctu
+import config
+
+redis_storage = redis.Redis(**config.REDIS_SERVER)
+storage = ctu.RedisCache(redis_storage, raw=True, ttl=120)
+crypto = ctu.EncryptedCache(storage, config.CACHE_KEY)
+cache = ctu.ToBytesCache(crypto)
+
+@ctu.cached(ctu.AutoPrefixedCache(cache), key=ctu.json_key)
+def repeat(s: str, n: int) -> str:
+    return s * n
+
+@ctu.cached(ctu.AutoPrefixedCache(cache), key=ctu.json_key)
+def banged(s: str, n: int) -> str:
+    return repeat(s, n) + "!"
+
+@ctu.cached(ctu.AutoPrefixedCache(cache), key=ctu.json_key)
+def question(s: str, n: int) -> str:
+    return repeat(s, n) + "?"
+
+print(banged("aa", 3))    # add 2 cache entries
+print(question("aa", 3))  # add 1 entry, 1 hit
+print(repeat("aa", 3))    # cache hit!
+print(banged("aa", 3))    # cache hit!
+
+assert cache.hits() > 0
+```
 
 ### Cache classes
 

{cachetoolsutils-10.3 → cachetoolsutils-11.0}/CacheToolsUtils.egg-info/requires.txt

@@ -12,15 +12,11 @@ ruff
 pytest
 coverage
 pymarkdownlnt
-types-redis
-types-cachetools
 
 [doc]
-sphinx
-sphinx_rtd_theme
-sphinx-autoapi
-sphinx-lint
-myst_parser
+mkdocs
+mkdocs-material
+mkdocstrings[python]
 
 [pub]
 build

{cachetoolsutils-10.3 → cachetoolsutils-11.0}/CacheToolsUtils.py

@@ -2,6 +2,9 @@
 CacheTools Utilities. This code is public domain.
 """
 
+# FIXME 3.13t checks without Cipher package
+# pyright: reportMissingImports=false
+
 from typing import Any, Callable, MutableMapping
 import abc
 
@@ -25,7 +28,7 @@ _NO_DEFAULT = object()
 
 
 class _MutMapMix:
-    """Convenient MutableMapping Mixin, forward to _cache."""
+    """Convenient MutableMapping Mixin, forward to `_cache`."""
 
     # FIXME coverage reports this as missing with Python 3.14
     _cache: MutableMapping  # pragma: no cover
@@ -50,7 +53,7 @@ class _MutMapMix:
 
 
 class _KeyMutMapMix(_MutMapMix):
-    """Convenient MutableMapping Mixin with a key filter, forward to _cache."""
+    """Convenient MutableMapping Mixin with a key filter, forward to `_cache`."""
 
     @abc.abstractmethod
     def _key(self, key: Any) -> Any:  # pragma: no cover
@@ -70,7 +73,7 @@ class _KeyMutMapMix(_MutMapMix):
 
 
 class _StatsMix:
-    """Convenient Mixin to forward stats methods to _cache."""
+    """Convenient Mixin to forward stats methods to `_cache`."""
 
     def hits(self) -> float|None:
         return self._cache.hits()  # type: ignore
@@ -111,9 +114,11 @@ class _RedisMix:  # pragma: no cover
 class DebugCache(_StatsMix, MutableMapping):
     """Debug class.
 
-    :param cache: actual cache
-    :param log: logging instance
-    :param name: name of instance for output
+    Parameters:
+
+    - cache: actual cache
+    - log: logging instance
+    - name: name of instance for output
     """
 
     def __init__(self, cache: MutableMapping, log: logging.Logger, name="cache"):
@@ -159,7 +164,7 @@ class DebugCache(_StatsMix, MutableMapping):
 
 
 class DictCache(_MutMapMix, MutableMapping):
-    """Cache class based on dict."""
+    """Cache class based on `dict`."""
 
     def __init__(self):
         self._cache = dict()
@@ -171,17 +176,19 @@ class DictCache(_MutMapMix, MutableMapping):
 class LockedCache(_MutMapMix, _StatsMix, _RedisMix, MutableMapping):
     """Cache class with a lock.
 
-    :param cache: actual cache.
-    :param lock: lock (context manager) to use
+    Parameters:
 
-    The locked layer should be the last one before the actual cache.
+    - cache: actual cache.
+    - lock: lock (context manager) to use
 
-    .. code-block: python
+    The locked layer should be the last one before the actual cache.
 
-       import threading
-       import cachetools as ct
-       import CacheToolsUtils as ctu
-       cache = ctu.LockedCache(ct.LFUCache(), threading.RLock())
+    ```python
+    import threading
+    import cachetools as ct
+    import CacheToolsUtils as ctu
+    cache = ctu.LockedCache(ct.LFUCache(), threading.RLock())
+    ```
     """
 
     def __init__(self, cache: MutableMapping, lock):
@@ -208,8 +215,10 @@ class LockedCache(_MutMapMix, _StatsMix, _RedisMix, MutableMapping):
 class PrefixedCache(_KeyMutMapMix, _StatsMix, MutableMapping):
     """Cache class to add a key prefix.
 
-    :param cache: actual cache.
-    :param prefix: prefix to prepend to keys.
+    Parameters:
+
+    - cache: actual cache.
+    - prefix: prefix to prepend to keys.
     """
 
     def __init__(self, cache: MutableMapping, prefix: str|bytes = ""):
@@ -229,9 +238,11 @@ class PrefixedCache(_KeyMutMapMix, _StatsMix, MutableMapping):
 class AutoPrefixedCache(PrefixedCache):
     """Cache class with an automatic counter-based string prefix.
 
-    :param cache: actual cache.
-    :param sep: prefix separator, default is ".".
-    :param method: encoding method in "b64", "b64u", "b32", "b32x", "b16",
+    Parameters:
+
+    - cache: actual cache.
+    - sep: prefix separator, default is ".".
+    - method: encoding method in "b64", "b64u", "b32", "b32x", "b16",
         "a85" and "b85". Default is "b64".
     """
 
@@ -262,16 +273,17 @@ class AutoPrefixedCache(PrefixedCache):
 class StatsCache(_MutMapMix, MutableMapping):
     """Cache class to keep stats.
 
-    :param cache: actual cache.
+    Parameter:
 
-    .. code-block: python
+    - cache: actual cache.
 
-       import cachetools as ct
-       import CacheToolsUtils as ctu
-       cache = ctu.StatsCache(ct.LRUCache())
-       ...
+    ```python
+    import cachetools as ct
+    import CacheToolsUtils as ctu
+    cache = ctu.StatsCache(ct.LRUCache())
+    ```
 
-    Note that CacheTools ``cached`` decorator with ``info=True`` provides
+    Note that CacheTools `cached` decorator with `info=True` provides
     hits, misses, maxsize and currsize information.
     However, this only works for its own classes.
     """
@@ -286,19 +298,25 @@ class StatsCache(_MutMapMix, MutableMapping):
 
     def reset(self):
         """Reset internal stats data."""
-        self._reads, self._writes, self._dels, self._hits = 0, 0, 0, 0
+        self._tests, self._reads, self._writes, self._dels, self._hits = 0, 0, 0, 0, 0
 
     def stats(self) -> dict[str, Any]:
         """Return available stats data as dict."""
         return {
             "type": 1,
+            "tests": self._tests,
             "reads": self._reads,
             "writes": self._writes,
             "dels": self._dels,
-            "hits": self.hits(),
+            "hits": self._hits,
+            "hit_rate": self.hits(),
             "size": self._cache.__len__()
         }
 
+    def __contains__(self, key):
+        self._tests += 1
+        return self._cache.__contains__(key)
+
     def __getitem__(self, key):
         self._reads += 1
         res = self._cache.__getitem__(key)
@@ -320,9 +338,11 @@ class StatsCache(_MutMapMix, MutableMapping):
 class TwoLevelCache(_MutMapMix, MutableMapping):
     """Two-Level Cache class for CacheTools.
 
-    :param cache: first (smaller, shorter TTL) cache
-    :param cache2: second (larger, longer TTL) cache
-    :param resilient: whether to ignore cache2 failures
+    Parameters:
+
+    - cache: first (smaller, shorter TTL) cache
+    - cache2: second (larger, longer TTL) cache
+    - resilient: whether to ignore cache2 failures
     """
 
     def __init__(self, cache: MutableMapping, cache2: MutableMapping, resilient=False):
@@ -448,10 +468,12 @@ class _Cipher:
 class EncryptedCache(_KeyMutMapMix, _StatsMix, MutableMapping):
     """Encrypted Bytes Key-Value Cache.
 
-    :param secret: bytes of secret, at least 16 bytes.
-    :param hsize: size of hashed key, default is *16*.
-    :param csize: value checksum size, default is *0*.
-    :param cipher: chose cipher from "Salsa20", "AES-128-CBC" or "ChaCha20".
+    Parameters:
+
+    - secret: bytes of secret, at least 16 bytes.
+    - hsize: size of hashed key, default is *16*.
+    - csize: value checksum size, default is *0*.
+    - cipher: chose cipher from "Salsa20", "AES-128-CBC" or "ChaCha20".
 
     The key is *not* encrypted but simply hashed, thus they are
     fixed size with a very low collision probability.
@@ -544,14 +566,16 @@ class ToBytesCache(_KeyMutMapMix, _StatsMix, MutableMapping):
 def cached(cache, *args, **kwargs):
     """Extended decorator with delete and exists.
 
-    All parameters are forwarded to ``cachetools.cached``.
+    All parameters are forwarded to `cachetools.cached`.
+
+    Parameter:
 
-    :param cache: actual cache.
+    - cache: actual cache.
 
-    If *f(\\*args, \\*\\*kwargs)* is the ``cached`` function, then:
+    If *f(\\*args, \\*\\*kwargs)* is the _cached_ function, then:
 
-    - ``f.cache_in(*args, **kwargs)`` tells whether the result is cached.
-    - ``f.cache_del(*args, **kwargs)`` deletes (invalidates) the cached result.
+    - `f.cache_in(*args, **kwargs)` tells whether the result is cached.
+    - `f.cache_del(*args, **kwargs)` deletes (invalidates) the cached result.
     """
 
     def decorate(fun: Callable):
@@ -594,15 +618,17 @@ def cacheMethods(
 ):
     """Cache some object methods.
 
-    :param cache: cache to use.
-    :param obj: object instance to be cached.
-    :param gen: generator of PrefixedCache.
-    :param opts: additional parameters when calling `cached`.
-    :param funs: name of methods and corresponding prefix
+    Parameters:
 
-    .. code-block:: python
+    - cache: cache to use.
+    - obj: object instance to be cached.
+    - gen: generator of PrefixedCache.
+    - opts: additional parameters when calling `cached`.
+    - funs: name of methods and corresponding prefix
 
-       cacheMethods(cache, item, PrefixedCache, compute1="c1.", compute2="c2.")
+    ```python
+    cacheMethods(cache, item, PrefixedCache, compute1="c1.", compute2="c2.")
+    ```
     """
     for fun, prefix in funs.items():
         assert hasattr(obj, fun), f"cannot cache missing method {fun} on {obj}"
@@ -621,15 +647,17 @@ def cacheFunctions(
 ):
     """Cache some global functions, with a prefix.
 
-    :param cache: cache to use.
-    :param globs: global object dictionary.
-    :param gen: generator of PrefixedCache.
-    :param opts: additional parameters when calling `cached`.
-    :param funs: name of functions and corresponding prefix
+    Parameters:
 
-    .. code-block:: python
+    - cache: cache to use.
+    - globs: global object dictionary.
+    - gen: generator of PrefixedCache.
+    - opts: additional parameters when calling `cached`.
+    - funs: name of functions and corresponding prefix
 
-       cacheFunctions(cache, globals(), PrefixedCache, fun1="f1.", fun2="f2.")
+    ```python
+    cacheFunctions(cache, globals(), PrefixedCache, fun1="f1.", fun2="f2.")
+    ```
     """
     for fun, prefix in funs.items():
         assert fun in globs, "caching functions: {fun} not found"
@@ -688,13 +716,13 @@ def full_hash_key(*args, **kwargs) -> str:
 # MEMCACHED
 #
 class JsonSerde:
-    """JSON serialize/deserialize class for MemCached (``pymemcache``).
+    """JSON serialize/deserialize class for MemCached (`pymemcache`).
 
-    .. code-block:: python
-
-       import pymemcache as pmc
-       import CacheToolsUtils as ctu
-       pmc_cache = pmc.Client(server="localhost", serde=ctu.JsonSerde())
+    ```python
+    import pymemcache as pmc
+    import CacheToolsUtils as ctu
+    pmc_cache = pmc.Client(server="localhost", serde=ctu.JsonSerde())
+    ```
     """
 
     # keep strings, else json
@@ -721,16 +749,19 @@ class JsonSerde:
 class MemCached(_KeyMutMapMix, MutableMapping):
     """MemCached-compatible wrapper class for cachetools with key encoding.
 
-    :param cache: actual memcached cache.
+    Parameter:
 
-    .. code-block:: python
+    - cache: actual memcached cache.
 
-       import pymemcache as pmc
-       import CacheToolsUtils as ctu
-       cache = ctu.MemCached(pmc.Client(server="localhost", serde=ctu.JsonSerde()))
+    ```python
+    import pymemcache as pmc
+    import CacheToolsUtils as ctu
+    cache = ctu.MemCached(pmc.Client(server="localhost", serde=ctu.JsonSerde()))
 
-       @ctu.cached(cache=cache)
-       def whatever(...):
+    @ctu.cached(cache=cache)
+    def whatever(...):
+        ...
+    ```
     """
 
     def __init__(self, cache):
@@ -764,15 +795,17 @@ class MemCached(_KeyMutMapMix, MutableMapping):
 class PrefixedMemCached(MemCached):
     """MemCached-compatible wrapper class for cachetools with a key prefix.
 
-    :param cache: actual memcached cache.
-    :param prefix: post key-encoding prepended prefix.
+    Parameters:
 
-    .. code-block:: python
+    - cache: actual memcached cache.
+    - prefix: post key-encoding prepended prefix.
 
-       import pymemcache as pmc
-       import CacheToolsUtils as ctu
-       # add a "app." prefix to keys, after serialization
-       cache = ctu.PrefixedMemCached(pmc.Client(server="localhost", serde=ctu.JsonSerde()), "app.")
+    ```python
+    import pymemcache as pmc
+    import CacheToolsUtils as ctu
+    # add a "app." prefix to keys, after serialization
+    cache = ctu.PrefixedMemCached(pmc.Client(server="localhost", serde=ctu.JsonSerde()), "app.")
+    ```
     """
 
     def __init__(self, cache, prefix: str = ""):
@@ -787,20 +820,22 @@ class PrefixedMemCached(MemCached):
 # REDIS
 #
 class RedisCache(MutableMapping):
-    """Redis TTL-ed wrapper for cachetools (``redis``).
+    """Redis TTL-ed wrapper for cachetools (`redis`).
 
-    :param cache: actual redis cache.
-    :param ttl: time-to-live in seconds, used as default expiration (``ex``), default is 600.
-    :param raw: whether to serialize keys and values, default is *False*.
+    Parameters:
 
-    Keys and values are serialized in *JSON*.
+    - cache: actual redis cache.
+    - ttl: time-to-live in seconds, used as default expiration (`ex`), default is _600_.
+    - raw: whether to serialize keys and values, default is *False*.
 
-    .. code-block:: python
+    Keys and values are serialized in *JSON*.
 
-       import redis
-       import CacheToolsUtils as ctu
-       # redis with 1 hour expiration
-       cache = ctu.RedisCache(redis.Redis(host="localhost"), 3600)
+    ```python
+    import redis
+    import CacheToolsUtils as ctu
+    # redis with 1 hour expiration
+    cache = ctu.RedisCache(redis.Redis(host="localhost"), 3600)
+    ```
     """
 
     def __init__(self, cache, ttl=600, raw=False):
@@ -880,16 +915,18 @@ class RedisCache(MutableMapping):
 class PrefixedRedisCache(RedisCache):
     """Prefixed Redis wrapper class for cachetools.
 
-    :param cache: actual redis cache.
-    :param prefix: post key encoding prefix, default is empty.
-    :param ttl: time-to-live in seconds, used as default expiration (``ex``), default is 600.
+    Parameters:
 
-    .. code-block:: python
+    - cache: actual redis cache.
+    - prefix: post key encoding prefix, default is empty.
+    - ttl: time-to-live in seconds, used as default expiration (`ex`), default is _600_.
 
-       import redis
-       import CacheToolsUtils as ctu
-       # redis with "app." prefix and 1 hour expiration
-       cache = ctu.PrefixedRedisCache(redis.Redis(host="localhost"), "app.", 3600)
+    ```python
+    import redis
+    import CacheToolsUtils as ctu
+    # redis with "app." prefix and 1 hour expiration
+    cache = ctu.PrefixedRedisCache(redis.Redis(host="localhost"), "app.", 3600)
+    ```
     """
 
     def __init__(self, cache, prefix: str = "", ttl=600):

{cachetoolsutils-10.3 → cachetoolsutils-11.0}/PKG-INFO

@@ -1,16 +1,15 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: CacheToolsUtils
-Version: 10.3
+Version: 11.0
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
-License: CC0
+License-Expression: CC0-1.0
 Project-URL: repository, https://github.com/zx80/cachetools-utils
 Project-URL: documentation, https://zx80.github.io/cachetools-utils/
 Project-URL: issues, https://github.com/zx80/cachetools-utils/issues
 Project-URL: package, https://pypi.org/project/CacheToolsUtils/
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
 Classifier: Programming Language :: Python
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
@@ -26,14 +25,10 @@ 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"
+Requires-Dist: mkdocs; extra == "doc"
+Requires-Dist: mkdocs-material; extra == "doc"
+Requires-Dist: mkdocstrings[python]; extra == "doc"
 Provides-Extra: crypt
 Requires-Dist: pycryptodome; extra == "crypt"
 Provides-Extra: tests
@@ -43,17 +38,16 @@ Provides-Extra: pub
 Requires-Dist: build; extra == "pub"
 Requires-Dist: wheel; extra == "pub"
 Requires-Dist: twine; extra == "pub"
+Dynamic: license-file
 
 # CacheToolsUtils
 
-Classes to add key prefix and stats to
-[cachetools](https://pypi.org/project/cachetools/) classes and use
-[redis](https://redis.io/) and
-[memcached](https://memcached.org/) as storage backends,
-and other cache-related utils.
+Stackable cache classes for sharing, encryption, statistics _and more_
+on top of [cachetools](https://pypi.org/project/cachetools/),
+[redis](https://redis.io/) and [memcached](https://memcached.org/).
 
-![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-23%20✓-success)
+![Status](https://github.com/zx80/cachetools-utils/actions/workflows/ctu.yml/badge.svg?branch=main&style=flat)
+![Tests](https://img.shields.io/badge/tests-25%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)
@@ -66,7 +60,37 @@ and other cache-related utils.
 For our purpose, a cache is a key-value store, aka a dictionary, possibly with
 some constraints on keys (type, size) and values (size, serialization).
 This module provides new caches, wrappers and other utilities suitable to use
-with `cachetools`.
+with `cachetools`. Example:
+
+```python
+import redis
+import CacheToolsUtils as ctu
+import config
+
+redis_storage = redis.Redis(**config.REDIS_SERVER)
+storage = ctu.RedisCache(redis_storage, raw=True, ttl=120)
+crypto = ctu.EncryptedCache(storage, config.CACHE_KEY)
+cache = ctu.ToBytesCache(crypto)
+
+@ctu.cached(ctu.AutoPrefixedCache(cache), key=ctu.json_key)
+def repeat(s: str, n: int) -> str:
+    return s * n
+
+@ctu.cached(ctu.AutoPrefixedCache(cache), key=ctu.json_key)
+def banged(s: str, n: int) -> str:
+    return repeat(s, n) + "!"
+
+@ctu.cached(ctu.AutoPrefixedCache(cache), key=ctu.json_key)
+def question(s: str, n: int) -> str:
+    return repeat(s, n) + "?"
+
+print(banged("aa", 3))    # add 2 cache entries
+print(question("aa", 3))  # add 1 entry, 1 hit
+print(repeat("aa", 3))    # cache hit!
+print(banged("aa", 3))    # cache hit!
+
+assert cache.hits() > 0
+```
 
 ### Cache classes
 

{cachetoolsutils-10.3 → cachetoolsutils-11.0}/README.md

@@ -1,13 +1,11 @@
 # CacheToolsUtils
 
-Classes to add key prefix and stats to
-[cachetools](https://pypi.org/project/cachetools/) classes and use
-[redis](https://redis.io/) and
-[memcached](https://memcached.org/) as storage backends,
-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-23%20✓-success)
+Stackable cache classes for sharing, encryption, statistics _and more_
+on top of [cachetools](https://pypi.org/project/cachetools/),
+[redis](https://redis.io/) and [memcached](https://memcached.org/).
+
+![Status](https://github.com/zx80/cachetools-utils/actions/workflows/ctu.yml/badge.svg?branch=main&style=flat)
+![Tests](https://img.shields.io/badge/tests-25%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)
@@ -20,7 +18,37 @@ and other cache-related utils.
 For our purpose, a cache is a key-value store, aka a dictionary, possibly with
 some constraints on keys (type, size) and values (size, serialization).
 This module provides new caches, wrappers and other utilities suitable to use
-with `cachetools`.
+with `cachetools`. Example:
+
+```python
+import redis
+import CacheToolsUtils as ctu
+import config
+
+redis_storage = redis.Redis(**config.REDIS_SERVER)
+storage = ctu.RedisCache(redis_storage, raw=True, ttl=120)
+crypto = ctu.EncryptedCache(storage, config.CACHE_KEY)
+cache = ctu.ToBytesCache(crypto)
+
+@ctu.cached(ctu.AutoPrefixedCache(cache), key=ctu.json_key)
+def repeat(s: str, n: int) -> str:
+    return s * n
+
+@ctu.cached(ctu.AutoPrefixedCache(cache), key=ctu.json_key)
+def banged(s: str, n: int) -> str:
+    return repeat(s, n) + "!"
+
+@ctu.cached(ctu.AutoPrefixedCache(cache), key=ctu.json_key)
+def question(s: str, n: int) -> str:
+    return repeat(s, n) + "?"
+
+print(banged("aa", 3))    # add 2 cache entries
+print(question("aa", 3))  # add 1 entry, 1 hit
+print(repeat("aa", 3))    # cache hit!
+print(banged("aa", 3))    # cache hit!
+
+assert cache.hits() > 0
+```
 
 ### Cache classes
 

{cachetoolsutils-10.3 → cachetoolsutils-11.0}/pyproject.toml

@@ -4,17 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "CacheToolsUtils"
-version = "10.3"
+version = "11.0"
 authors = [ { name = "Fabien Coelho", email = "cachetools.utils@coelho.net" } ]
 description = "Cachetools Utilities"
 readme = "README.md"
-license = { text = "CC0" }
+license = "CC0-1.0"
 requires-python = ">= 3.10"
 dependencies = [ "cachetools" ]
 classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Intended Audience :: Developers",
-  "License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication",
   "Programming Language :: Python",
   "Topic :: Software Development :: Libraries :: Python Modules"
 ]
@@ -30,8 +29,14 @@ package = "https://pypi.org/project/CacheToolsUtils/"
 py-modules = [ "CacheToolsUtils" ]
 
 [project.optional-dependencies]
-dev = [ "mypy", "pyright", "black", "flake8", "ruff", "pytest", "coverage", "pymarkdownlnt", "types-redis", "types-cachetools" ]
-doc = [ "sphinx", "sphinx_rtd_theme", "sphinx-autoapi", "sphinx-lint", "myst_parser" ]
+dev = [
+  "mypy", "pyright",
+  # "types-redis", "types-cachetools",
+  "black", "flake8", "ruff",
+  "pytest", "coverage",
+  "pymarkdownlnt",
+]
+doc = [ "mkdocs", "mkdocs-material", "mkdocstrings[python]" ]
 crypt = [ "pycryptodome" ]
 tests = [ "pymemcache", "redis" ]
 pub = [ "build", "wheel", "twine" ]