CacheToolsUtils 10.1__tar.gz → 10.3__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: CacheToolsUtils
-Version: 10.1
+Version: 10.3
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -53,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-22%20✓-success)
+![Tests](https://img.shields.io/badge/tests-23%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)
@@ -81,6 +81,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.1 → cachetoolsutils-10.3}/CacheToolsUtils.py

@@ -226,6 +226,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.
 
@@ -367,6 +400,48 @@ class TwoLevelCache(_MutMapMix, MutableMapping):
         self._cache2.reset()  # type: ignore
 
 
+# NOTE this is quite costly, a Cipher object is created to encrypt/decrypt each value.
+# another design could keep a persistant cipher.
+class _Cipher:
+    """Not so convincing internal class to abstract cipher algorithms."""
+
+    def __init__(self, name):
+        self._name = name
+        if name == "Salsa20":
+            from Crypto.Cipher import Salsa20 as cipher
+            # NOTE hash and nonce may overlap, which is not an issue
+            params = {"key": (32, 64), "nonce": (24, 32)}
+            kwargs = {}
+            size = 0
+        elif name == "ChaCha20":
+            from Crypto.Cipher import ChaCha20 as cipher
+            # NOTE hash and nonce may overlap, which is not an issue
+            params = {"key": (32, 64), "nonce": (24, 32)}
+            kwargs = {}
+            size = 0
+        elif name in ("AES", "AES-128", "AES-128-CBC"):
+            from Crypto.Cipher import AES as cipher
+            params = {"key": (48, 64), "iv": (32, 48)}
+            kwargs = {"mode": cipher.MODE_CBC}
+            size = 16
+        else:
+            raise Exception(f"unexpected cipher: {name}")
+        self._cipher = cipher
+        self._params = params
+        self._kwargs = kwargs
+        if size:
+            from Crypto.Util.Padding import pad, unpad
+            self._pad = lambda s: pad(s, size)
+            self._unpad = lambda s: unpad(s, size)
+        else:
+            self._pad = lambda s: s
+            self._unpad = lambda s: s
+
+    def new(self, derived: bytes):
+        kwargs = {k: derived[v[0]: v[1]] for k, v in self._params.items()}
+        return self._cipher.new(**kwargs, **self._kwargs)  # type: ignore
+
+
 #
 # Encrypted Cache
 #
@@ -376,6 +451,7 @@ class EncryptedCache(_KeyMutMapMix, _StatsMix, MutableMapping):
     :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".
 
     The key is *not* encrypted but simply hashed, thus they are
     fixed size with a very low collision probability.
@@ -384,11 +460,12 @@ class EncryptedCache(_KeyMutMapMix, _StatsMix, MutableMapping):
     as each value is encrypted with its own key and nonce.
 
     Algorithms:
+
     - SHA3: hash/key/nonce derivation and checksum.
-    - Salsa20: value encryption.
+    - Salsa20, AES-128-CBC or ChaCha20: value encryption.
     """
 
-    def __init__(self, cache: MutableMapping, secret: bytes, hsize: int = 16, csize: int = 0):
+    def __init__(self, cache: MutableMapping, secret: bytes, hsize: int = 16, csize: int = 0, cipher: str = "Salsa20"):
         self._cache = cache
         assert len(secret) >= 16
         self._secret = secret
@@ -396,34 +473,31 @@ class EncryptedCache(_KeyMutMapMix, _StatsMix, MutableMapping):
         self._hsize = hsize
         assert 0 <= csize <= 32
         self._csize = csize
-        from Crypto.Cipher import Salsa20
-        self._cipher = Salsa20
+        self._cipher = _Cipher(cipher)
 
-    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 _derive(self, key) -> tuple[bytes, bytes]:
+        """Derive hash and stuff from initial key and secret."""
+        derived = hashlib.sha3_512(key + self._secret).digest()
+        return (derived[:self._hsize], derived)
 
     def _key(self, key):
-        return self._keydev(key)[0]
+        return self._derive(key)[0]
 
     def __setitem__(self, key, val):
-        hkey, vkey, vnonce = self._keydev(key)
-        xval = self._cipher.new(key=vkey, nonce=vnonce).encrypt(val)
+        hkey, derived = self._derive(key)
+        xval = self._cipher.new(derived).encrypt(self._cipher._pad(val))
         if self._csize:
-            cs = hashlib.sha3_256(val).digest()[:self._csize]
-            xval = cs + xval
+            xval = hashlib.sha3_256(val).digest()[:self._csize] + xval
         self._cache[hkey] = xval
 
     def __getitem__(self, key):
-        hkey, vkey, vnonce = self._keydev(key)
+        hkey, derived = self._derive(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)
+        val = self._cipher._unpad(self._cipher.new(derived).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
@@ -597,7 +671,9 @@ class _HashJsonKey:
         return self._key
 
 
+# NOTE not very useful, behaves as _HashJsonKey.
 def hash_json_key(*args, **kwargs):
+    """Function handling of above class, to keep it hidden."""
     return _HashJsonKey(*args, **kwargs)
 
 
@@ -639,7 +715,7 @@ class JsonSerde:
         elif flag == 3:
             return json.loads(value.decode("utf-8"))
         else:
-            raise Exception("Unknown serialization format")
+            raise Exception(f"Unknown serialization format: {flag}")
 
 
 class MemCached(_KeyMutMapMix, MutableMapping):

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: CacheToolsUtils
-Version: 10.1
+Version: 10.3
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -53,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-22%20✓-success)
+![Tests](https://img.shields.io/badge/tests-23%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)
@@ -81,6 +81,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.1 → cachetoolsutils-10.3}/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-22%20✓-success)
+![Tests](https://img.shields.io/badge/tests-23%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)
@@ -35,6 +35,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.1 → cachetoolsutils-10.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "CacheToolsUtils"
-version = "10.1"
+version = "10.3"
 authors = [ { name = "Fabien Coelho", email = "cachetools.utils@coelho.net" } ]
 description = "Cachetools Utilities"
 readme = "README.md"