CacheToolsUtils 9.3__tar.gz → 10.1__tar.gz

{cachetoolsutils-9.3 → cachetoolsutils-10.1}/CacheToolsUtils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CacheToolsUtils
-Version: 9.3
+Version: 10.1
 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,17 @@ 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.
+- `BytesCache` map bytes keys and values to strings.
 
 ### 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.3 → cachetoolsutils-10.1}/CacheToolsUtils.egg-info/requires.txt

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

{cachetoolsutils-9.3 → cachetoolsutils-10.1}/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
 
@@ -365,6 +367,106 @@ class TwoLevelCache(_MutMapMix, MutableMapping):
         self._cache2.reset()  # type: ignore
 
 
+#
+# 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*.
+    :param csize: value checksum size, default is *0*.
+
+    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 and nonce.
+
+    Algorithms:
+    - SHA3: hash/key/nonce derivation and checksum.
+    - Salsa20: value encryption.
+    """
+
+    def __init__(self, cache: MutableMapping, secret: bytes, hsize: int = 16, csize: int = 0):
+        self._cache = cache
+        assert len(secret) >= 16
+        self._secret = secret
+        assert 8 <= hsize <= 32
+        self._hsize = hsize
+        assert 0 <= csize <= 32
+        self._csize = csize
+        from Crypto.Cipher import Salsa20
+        self._cipher = Salsa20
+
+    def _keydev(self, key) -> tuple[bytes, bytes, bytes]:
+        """Compute hash, key and nonce from initial key."""
+        hkey = hashlib.sha3_512(key + self._secret).digest()
+        # NOTE hash and nonce may overlap, which is not an issue
+        return (hkey[:self._hsize], hkey[32:], hkey[24:32])
+
+    def _key(self, key):
+        return self._keydev(key)[0]
+
+    def __setitem__(self, key, val):
+        hkey, vkey, vnonce = self._keydev(key)
+        xval = self._cipher.new(key=vkey, nonce=vnonce).encrypt(val)
+        if self._csize:
+            cs = hashlib.sha3_256(val).digest()[:self._csize]
+            xval = cs + xval
+        self._cache[hkey] = xval
+
+    def __getitem__(self, key):
+        hkey, vkey, vnonce = self._keydev(key)
+        xval = self._cache[hkey]
+        if self._csize:  # split cs from encrypted value
+            cs, xval = xval[:self._csize], xval[self._csize:]
+        else:
+            cs = None
+        val = self._cipher.new(key=vkey, nonce=vnonce).decrypt(xval)
+        if self._csize and cs != hashlib.sha3_256(val).digest()[:self._csize]:
+            raise KeyError(f"invalid encrypted value for key {key}")
+        return val
+
+
+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"))
+
+
+#
+# CACHED DECORATOR AND HELPERS
+#
 def cached(cache, *args, **kwargs):
     """Extended decorator with delete and exists.
 
@@ -465,7 +567,9 @@ def cacheFunctions(
 
 # 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}
@@ -476,19 +580,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):
@@ -499,6 +601,13 @@ 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")
+
+
 #
 # MEMCACHED
 #
@@ -514,16 +623,20 @@ class JsonSerde:
 
     # keep strings, else json
     def serialize(self, key, value):
-        if isinstance(value, str):
-            return value.encode("utf-8"), 1
+        if isinstance(value, bytes):
+            return value, 1
+        elif isinstance(value, str):
+            return value.encode("utf-8"), 2
         else:
-            return json.dumps(value, sort_keys=True).encode("utf-8"), 2
+            return json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8"), 3
 
     # reverse previous serialization
     def deserialize(self, key, value, flag):
         if flag == 1:
-            return value.decode("utf-8")
+            return value
         elif flag == 2:
+            return value.decode("utf-8")
+        elif flag == 3:
             return json.loads(value.decode("utf-8"))
         else:
             raise Exception("Unknown serialization format")
@@ -553,8 +666,6 @@ class MemCached(_KeyMutMapMix, MutableMapping):
     # short (250 bytes) ASCII without control chars nor spaces
     # 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):
@@ -593,30 +704,18 @@ class PrefixedMemCached(MemCached):
         self._prefix = bytes(prefix, "utf-8")
 
     def _key(self, key):
-        import base64
-
         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*.
 
@@ -628,24 +727,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))
@@ -725,10 +825,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.3 → cachetoolsutils-10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CacheToolsUtils
-Version: 9.3
+Version: 10.1
 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,17 @@ 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.
+- `BytesCache` map bytes keys and values to strings.
 
 ### 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.3 → cachetoolsutils-10.1}/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,17 @@ 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.
+- `BytesCache` map bytes keys and values to strings.
 
 ### 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.3 → cachetoolsutils-10.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "CacheToolsUtils"
-version = "9.3"
+version = "10.1"
 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" ]