CacheToolsUtils 9.2__tar.gz → 10.0__tar.gz

{cachetoolsutils-9.2 → cachetoolsutils-10.0}/CacheToolsUtils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CacheToolsUtils
-Version: 9.2
+Version: 10.0
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -34,6 +34,8 @@ 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: crypt
+Requires-Dist: pycryptodome; extra == "crypt"
 Provides-Extra: tests
 Requires-Dist: pymemcache; extra == "tests"
 Requires-Dist: redis; extra == "tests"
@@ -51,7 +53,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-21%20✓-success)
+![Tests](https://img.shields.io/badge/tests-22%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)
@@ -85,13 +87,16 @@ with `cachetools`.
 - `LockedCache` use a (thread) lock to control cache accesses.
 - `TwoLevelCache` allows to combine two caches.
 - `DebugCache` to trace cache calls using `logging`.
+- `EncryptedCache` a cache with key hashing and value encryption.
+- `ToBytesCache` map keys and values to bytes.
 
 ### Cache utilities
 
 - `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
+- `json_key`, `hash_json_key`, `full_hash_key`: convenient JSON-based cache key
+  serialization functions for `cached`.
 
 ## License
 

{cachetoolsutils-9.2 → cachetoolsutils-10.0}/CacheToolsUtils.egg-info/requires.txt

@@ -1,5 +1,8 @@
 cachetools
 
+[crypt]
+pycryptodome
+
 [dev]
 mypy
 pyright

{cachetoolsutils-9.2 → cachetoolsutils-10.0}/CacheToolsUtils.py

@@ -5,6 +5,8 @@ CacheTools Utilities. This code is public domain.
 from typing import Any, Callable, MutableMapping
 import abc
 
+import base64
+import hashlib
 import cachetools
 import json
 
@@ -380,10 +382,10 @@ def cached(cache, *args, **kwargs):
 
     def decorate(fun: Callable):
 
-        # use cachetools
+        # use cachetools "cached" decorator
         fun = cachetools.cached(cache, *args, **kwargs)(fun)
 
-        # extend
+        # extend it with two functions
         def cache_in(*args, **kwargs) -> bool:
             """Tell whether key is already in cache."""
             key = fun.cache_key(*args, **kwargs)  # type: ignore
@@ -409,12 +411,19 @@ def cached(cache, *args, **kwargs):
 MapGen = Callable[[MutableMapping, str], MutableMapping]
 
 
-def cacheMethods(cache: MutableMapping, obj: Any, gen: MapGen = PrefixedCache, **funs):
+def cacheMethods(
+    cache: MutableMapping,
+    obj: Any,
+    gen: MapGen = PrefixedCache,
+    opts: dict[str, Any] = {},
+    **funs
+):
     """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
 
     .. code-block:: python
@@ -426,17 +435,22 @@ def cacheMethods(cache: MutableMapping, obj: Any, gen: MapGen = PrefixedCache, *
         f = getattr(obj, fun)
         while hasattr(f, "__wrapped__"):
             f = f.__wrapped__
-        setattr(obj, fun, cached(cache=gen(cache, prefix))(f))
+        setattr(obj, fun, cached(cache=gen(cache, prefix), **opts)(f))
 
 
 def cacheFunctions(
-    cache: MutableMapping, globs: MutableMapping[str, Any], gen: MapGen = PrefixedCache, **funs
+    cache: MutableMapping,
+    globs: MutableMapping[str, Any],
+    gen: MapGen = PrefixedCache,
+    opts: dict[str, Any] = {},
+    **funs
 ):
     """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
 
     .. code-block:: python
@@ -448,12 +462,14 @@ def cacheFunctions(
         f = globs[fun]
         while hasattr(f, "__wrapped__"):
             f = f.__wrapped__
-        globs[fun] = cached(cache=gen(cache, prefix))(f)
+        globs[fun] = cached(cache=gen(cache, prefix), **opts)(f)
 
 
 # JSON-based key function
 # NOTE obviously this only works if parameters are json-serializable…
-def json_key(*args, **kwargs):
+def json_key(*args, **kwargs) -> str:
+    """JSON serialization of arguments."""
+    val: Any
     if kwargs:  # object
         if args:
             val = {"*": args, "**": kwargs}
@@ -464,19 +480,17 @@ def json_key(*args, **kwargs):
     return json.dumps(val, sort_keys=True, separators=(",", ":"))
 
 
-# Hmmm…
+# Hmmm… is this useful?
 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)
+        self._hashed = self._key.__hash__()
 
     def __hash__(self):
-        if self._hashed is None:
-            self._hashed = self._key.__hash__()
         return self._hashed
 
     def __str__(self):
@@ -487,9 +501,100 @@ def hash_json_key(*args, **kwargs):
     return _HashJsonKey(*args, **kwargs)
 
 
+def full_hash_key(*args, **kwargs) -> str:
+    """Reduce arguments to a single 128-bits hash."""
+    skey = json_key(*args, **kwargs)
+    hkey = hashlib.sha3_256(skey.encode("UTF-8")).digest()[:16]
+    return base64.b85encode(hkey).decode("ASCII")
+
+
+#
+# Encrypted Cache
+#
+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.
+
+    The key is *not* encrypted but simply hashed, thus they are
+    fixed size with a very low collision probability.
+
+    By design, the clear-text key is needed to recover the value,
+    as each value is encrypted with its own key.
+
+    There is no integrity check on the value.
+
+    Algorithms:
+    - SHA3: hash/key/nonce derivation.
+    - Salsa20: value encryption.
+    """
+
+    def __init__(self, cache: MutableMapping, secret: bytes, hsize: int = 16):
+        self._cache = cache
+        assert len(secret) >= 16
+        self._secret = secret
+        assert 8 <= hsize <= 24
+        self._hsize = hsize
+        from Crypto.Cipher import Salsa20
+        self._cipher = Salsa20
+
+    def _keydev(self, key):
+        hkey = hashlib.sha3_512(key + self._secret).digest()
+        sz = self._hsize
+        return (hkey[:sz], hkey[sz:sz+32], hkey[sz+32:sz+40])
+
+    def _key(self, key):
+        return self._keydev(key)[0]
+
+    def __setitem__(self, key, val):
+        hkey, vkey, vnonce = self._keydev(key)
+        self._cache[hkey] = self._cipher.new(key=vkey, nonce=vnonce).encrypt(val)
+
+    def __getitem__(self, key):
+        hkey, vkey, vnonce = self._keydev(key)
+        return self._cipher.new(key=vkey, nonce=vnonce).decrypt(self._cache[hkey])
+
+
+class BytesCache(_KeyMutMapMix, _StatsMix, MutableMapping):
+    """Map bytes to strings."""
+
+    def __init__(self, cache):
+        self._cache = cache
+
+    def _key(self, key):
+        # assert isinstance(key, bytes)
+        return base64.b85encode(key).decode("ASCII")
+
+    def __setitem__(self, key, val):
+        self._cache.__setitem__(self._key(key), self._key(val))
+
+    def __getitem__(self, key):
+        val = self._cache.__getitem__(self._key(key))
+        # assert isinstance(val, str)
+        return base64.b85decode(val)
+
+
+class ToBytesCache(_KeyMutMapMix, _StatsMix, MutableMapping):
+    """Map (JSON-serializable) cache keys and values to bytes."""
+
+    def __init__(self, cache):
+        self._cache = cache
+
+    def _key(self, key):
+        return json.dumps(key, sort_keys=True, separators=(",", ":")).encode("UTF-8")
+
+    def __setitem__(self, key, val):
+        self._cache.__setitem__(self._key(key), self._key(val))
+
+    def __getitem__(self, key):
+        return json.loads(self._cache.__getitem__(self._key(key)).decode("UTF-8"))
+
+
 #
 # MEMCACHED
 #
+# FIXME what about bytes?
 class JsonSerde:
     """JSON serialize/deserialize class for MemCached (``pymemcache``).
 
@@ -504,8 +609,10 @@ class JsonSerde:
     def serialize(self, key, value):
         if isinstance(value, str):
             return value.encode("utf-8"), 1
+        elif isinstance(value, bytes):
+            return value, 3
         else:
-            return json.dumps(value, sort_keys=True).encode("utf-8"), 2
+            return json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8"), 2
 
     # reverse previous serialization
     def deserialize(self, key, value, flag):
@@ -513,6 +620,8 @@ class JsonSerde:
             return value.decode("utf-8")
         elif flag == 2:
             return json.loads(value.decode("utf-8"))
+        elif flag == 3:
+            return value
         else:
             raise Exception("Unknown serialization format")
 
@@ -586,25 +695,15 @@ class PrefixedMemCached(MemCached):
         return self._prefix + base64.b85encode(str(key).encode("utf-8"))
 
 
-class StatsMemCached(MemCached):
-    """Cache MemCached-compatible class with stats.
-
-    This class is empty and only kept for compatibility.
-    """
-
-    pass
-
-
 #
 # REDIS
 #
-
-
 class RedisCache(MutableMapping):
     """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*.
 
     Keys and values are serialized in *JSON*.
 
@@ -616,24 +715,25 @@ class RedisCache(MutableMapping):
        cache = ctu.RedisCache(redis.Redis(host="localhost"), 3600)
     """
 
-    def __init__(self, cache, ttl=600):
+    def __init__(self, cache, ttl=600, raw=False):
         # import redis
         # assert isinstance(cache, redis.Redis)
         self._cache = cache
         self._ttl = ttl
+        self._raw = raw
 
     def clear(self):  # pragma: no cover
         """Flush Redis contents."""
         return self._cache.flushdb()
 
     def _serialize(self, s):
-        return json.dumps(s, sort_keys=True)
+        return s if self._raw else json.dumps(s, sort_keys=True, separators=(",", ":"))
 
     def _deserialize(self, s):
-        return json.loads(s)
+        return s if self._raw else json.loads(s)
 
     def _key(self, key):
-        return json.dumps(key, sort_keys=True)
+        return key if self._raw else json.dumps(key, sort_keys=True, separators=(",", ":"))
 
     def __getitem__(self, index):
         val = self._cache.get(self._key(index))
@@ -713,10 +813,11 @@ class PrefixedRedisCache(RedisCache):
         return self._prefix + str(key)
 
 
+# FIXME should it be removed?
 class StatsRedisCache(PrefixedRedisCache):
     """TTL-ed Redis wrapper class for cachetools.
 
-    This class is empty and only kept for compatibility.
+    This class is nearly empty.
     """
 
     def flushdb(self):

{cachetoolsutils-9.2 → cachetoolsutils-10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CacheToolsUtils
-Version: 9.2
+Version: 10.0
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -34,6 +34,8 @@ 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: crypt
+Requires-Dist: pycryptodome; extra == "crypt"
 Provides-Extra: tests
 Requires-Dist: pymemcache; extra == "tests"
 Requires-Dist: redis; extra == "tests"
@@ -51,7 +53,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-21%20✓-success)
+![Tests](https://img.shields.io/badge/tests-22%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)
@@ -85,13 +87,16 @@ with `cachetools`.
 - `LockedCache` use a (thread) lock to control cache accesses.
 - `TwoLevelCache` allows to combine two caches.
 - `DebugCache` to trace cache calls using `logging`.
+- `EncryptedCache` a cache with key hashing and value encryption.
+- `ToBytesCache` map keys and values to bytes.
 
 ### Cache utilities
 
 - `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
+- `json_key`, `hash_json_key`, `full_hash_key`: convenient JSON-based cache key
+  serialization functions for `cached`.
 
 ## License
 

{cachetoolsutils-9.2 → cachetoolsutils-10.0}/README.md

@@ -7,7 +7,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-21%20✓-success)
+![Tests](https://img.shields.io/badge/tests-22%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)
@@ -41,13 +41,16 @@ with `cachetools`.
 - `LockedCache` use a (thread) lock to control cache accesses.
 - `TwoLevelCache` allows to combine two caches.
 - `DebugCache` to trace cache calls using `logging`.
+- `EncryptedCache` a cache with key hashing and value encryption.
+- `ToBytesCache` map keys and values to bytes.
 
 ### Cache utilities
 
 - `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
+- `json_key`, `hash_json_key`, `full_hash_key`: convenient JSON-based cache key
+  serialization functions for `cached`.
 
 ## License
 

{cachetoolsutils-9.2 → cachetoolsutils-10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "CacheToolsUtils"
-version = "9.2"
+version = "10.0"
 authors = [ { name = "Fabien Coelho", email = "cachetools.utils@coelho.net" } ]
 description = "Cachetools Utilities"
 readme = "README.md"
@@ -32,5 +32,6 @@ 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" ]
+crypt = [ "pycryptodome" ]
 tests = [ "pymemcache", "redis" ]
 pub = [ "build", "wheel", "twine" ]