CacheToolsUtils 10.2__tar.gz → 10.4__tar.gz

{cachetoolsutils-10.2 → cachetoolsutils-10.4}/CacheToolsUtils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: CacheToolsUtils
-Version: 10.2
+Version: 10.4
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -26,8 +26,6 @@ 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"
@@ -46,14 +44,12 @@ Requires-Dist: twine; extra == "pub"
 
 # 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-22%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 +62,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
 
@@ -81,6 +107,7 @@ with `cachetools`.
 
 - `PrefixedCache`, `PrefixedMemCached` and `PrefixedRedisCache` add a prefix to
   distinguish sources on a shared cache.
+- `AutoPrefixedCache` add a counter-based prefix.
 - `StatsCache`, `MemCached` and `RedisCache` add a `hits` method
   to report the cache hit rate, `stats` to report statistics and
   `reset` to reset statistics.

{cachetoolsutils-10.2 → cachetoolsutils-10.4}/CacheToolsUtils.egg-info/requires.txt

@@ -12,8 +12,6 @@ ruff
 pytest
 coverage
 pymarkdownlnt
-types-redis
-types-cachetools
 
 [doc]
 sphinx

{cachetoolsutils-10.2 → cachetoolsutils-10.4}/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
 
@@ -226,6 +229,39 @@ class PrefixedCache(_KeyMutMapMix, _StatsMix, MutableMapping):
         return self._prefix + self._cast(key)  # type: ignore
 
 
+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",
+        "a85" and "b85". Default is "b64".
+    """
+
+    _COUNTER: int = 0
+
+    _METHODS: dict[str, Callable[[Any], bytes]] = {
+        "b64": base64.b64encode,
+        "b64u": base64.urlsafe_b64encode,
+        "b32": base64.b32encode,
+        "b32x": base64.b32hexencode,
+        "b16": base64.b16encode,
+        "a85": base64.a85encode,
+        "b85": base64.b85encode,
+        # "z85": base64.z85encode,  # Python 3.13
+    }
+
+    def __init__(self, cache: MutableMapping, sep: str = ".", method: str = "b64"):
+        if method not in AutoPrefixedCache._METHODS:
+            raise Exception(f"invalid conversion method: {method}")
+        encoder = AutoPrefixedCache._METHODS[method]
+        length = max(1, (AutoPrefixedCache._COUNTER.bit_length() + 7) // 8)
+        # NOTE byteorder default added to 3.11
+        prefix = encoder(AutoPrefixedCache._COUNTER.to_bytes(length, byteorder="big")).decode("ASCII")
+        AutoPrefixedCache._COUNTER += 1
+        super().__init__(cache, prefix + sep)
+
+
 class StatsCache(_MutMapMix, MutableMapping):
     """Cache class to keep stats.
 
@@ -253,19 +289,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)

{cachetoolsutils-10.2 → cachetoolsutils-10.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: CacheToolsUtils
-Version: 10.2
+Version: 10.4
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -26,8 +26,6 @@ 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"
@@ -46,14 +44,12 @@ Requires-Dist: twine; extra == "pub"
 
 # 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-22%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 +62,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
 
@@ -81,6 +107,7 @@ with `cachetools`.
 
 - `PrefixedCache`, `PrefixedMemCached` and `PrefixedRedisCache` add a prefix to
   distinguish sources on a shared cache.
+- `AutoPrefixedCache` add a counter-based prefix.
 - `StatsCache`, `MemCached` and `RedisCache` add a `hits` method
   to report the cache hit rate, `stats` to report statistics and
   `reset` to reset statistics.

{cachetoolsutils-10.2 → cachetoolsutils-10.4}/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-22%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
 
@@ -35,6 +63,7 @@ with `cachetools`.
 
 - `PrefixedCache`, `PrefixedMemCached` and `PrefixedRedisCache` add a prefix to
   distinguish sources on a shared cache.
+- `AutoPrefixedCache` add a counter-based prefix.
 - `StatsCache`, `MemCached` and `RedisCache` add a `hits` method
   to report the cache hit rate, `stats` to report statistics and
   `reset` to reset statistics.

{cachetoolsutils-10.2 → cachetoolsutils-10.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "CacheToolsUtils"
-version = "10.2"
+version = "10.4"
 authors = [ { name = "Fabien Coelho", email = "cachetools.utils@coelho.net" } ]
 description = "Cachetools Utilities"
 readme = "README.md"
@@ -30,7 +30,13 @@ 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" ]
+dev = [
+  "mypy", "pyright",
+  # "types-redis", "types-cachetools",
+  "black", "flake8", "ruff",
+  "pytest", "coverage",
+  "pymarkdownlnt",
+]
 doc = [ "sphinx", "sphinx_rtd_theme", "sphinx-autoapi", "sphinx-lint", "myst_parser" ]
 crypt = [ "pycryptodome" ]
 tests = [ "pymemcache", "redis" ]