HermesCache

https://hermescache.readthedocs.io/
Admin
HermesCache is a Python caching library providing tag-based cache invalidation, dogpile effect...
Tokens:24,875
Snippets:254
Trust Score:9.6
Update:2 days ago
Show doc for...
Tokens:
Raw
### HermesCache Quickstart Example

Source: https://hermescache.readthedocs.io/en/latest/?badge=latest

Demonstrates the main HermesCache API: creating a Hermes facade with a Redis backend, decorating functions and methods with caching, using tags and custom keys, invalidating entries, and cleaning the cache.

```python
import hermes.backend.redis


cache = hermes.Hermes(
  hermes.backend.redis.Backend,
  ttl = 600,
  host = 'localhost',
  db = 1,
)

@cache
def foo(a, b):
  return a * b

class Example:

  @cache(tags = ('math', 'power'), ttl = 1200)
  def bar(self, a, b):
    return a ** b

  @cache(tags = ('math', 'avg'), key = lambda fn, a, b: f'avg:{a}:{b}')
  def baz(self, a, b):
    return (a + b) / 2

print(foo(2, 333))

example = Example()
print(example.bar(2, 10))
print(example.baz(2, 10))

foo.invalidate(2, 333)
example.bar.invalidate(2, 10)
example.baz.invalidate(2, 10)

cache.clean(['math']) # invalidate entries tagged 'math'
cache.clean()         # flush cache
```

--------------------------------

### Install HermesCache with pip

Source: https://hermescache.readthedocs.io/en/latest/?badge=latest

Install the HermesCache package using pip. This is the standard installation command.

```bash
pip install HermesCache
```

--------------------------------

### Cache invalidation and cleaning example

Source: https://hermescache.readthedocs.io/en/report/htmlcov/z_29e638db6e54f801___init___py.html

Example usage of the Cache class showing how to invalidate specific entries and clean the cache by tag or flush it entirely.

```python
foo.invalidate(2, 333)
```

```python
example.bar.invalidate(2, 10)
```

```python
example.baz.invalidate(2, 10)
```

```python
cache.clean(['math']) # invalidate entries tagged 'math'
```

```python
cache.clean() # flush cache
```

--------------------------------

### AsyncBackend.startWatch

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Starts the TTL watching task. Must be called when the asyncio IO loop is running.

```APIDOC
## AsyncBackend.startWatch

### Description
Start TTL watching task.

### Method
startWatch

### Notes
It must be called when `asyncio` IO loop is running.
```

--------------------------------

### Example of dynamically created cached functions

Source: https://hermescache.readthedocs.io/en/report/htmlcov/z_29e638db6e54f801___init___py.html

Shows two functions f created dynamically in the same module with the same name, each decorated with @cache, returning different results. The example prints the result of calling createF1()(1, 2).

```python
def createF1():
    @cache
    def f(a, b):
        return a + b
    return f

def createF2():
    @cache
    def f(a, b):
        return a * b
    return f

print(createF1()(1, 2))
```

--------------------------------

### HermesCache Hermes usage with Redis backend and decorators

Source: https://hermescache.readthedocs.io/en/report/htmlcov/z_29e638db6e54f801___init___py.html

Example usage of the Hermes class with a Redis backend. It demonstrates creating a cache instance, decorating a function and methods with @cache, using tags and TTL, and a custom key function. The example includes print statements showing how to call the cached functions.

```python
import hermes.backend.redis

cache = hermes.Hermes(
    hermes.backend.redis.Backend, ttl = 600, host = 'localhost', db = 1
)

@cache
def foo(a, b):
    return a * b

class Example:

    @cache(tags = ('math', 'power'), ttl = 1200)
    def bar(self, a, b):
        return a ** b

    @cache(
        tags = ('math', 'avg'),
        key = lambda fn, *args, **kwargs: 'avg:{0}:{1}'.format(*args),
    )
    def baz(self, a, b):
        return (a + b) / 2.0

print(foo(2, 333))

example = Example()
print(example.bar(2, 10))
print(example.baz(2, 10))
```

--------------------------------

### Async caching with Redis backend

Source: https://hermescache.readthedocs.io/en/latest/asyncio.html

Example of using Hermes with the Redis backend to cache an async function that fetches data from PyPI. The cache decorator is applied with a TTL and tags, and the example shows how to call the cached function and invalidate entries.

```python
import aiohttp
import hermes.backend.redis


cache = hermes.Hermes(
  hermes.backend.redis.Backend,
  ttl = 600,
  host = 'localhost',
  db = 1,
)

@cache(ttl = 365 * 24 * 3600, tags = ['pypi'])
async def getHash(version):
  async with aiohttp.ClientSession() as session:
    async with session.get('https://pypi.org/pypi/hermescache/json') as resp:
      return (await resp.json())['releases'][version][0]['md5_digest']

print(await getHash('0.9.0'))
print(await getHash('0.8.0'))
print(await getHash('0.7.2'))

await getHash.invalidate('0.8.0')
cache.clean(['pypi'])  # invalidate entries tagged 'pypi'
```

--------------------------------

### Basic caching with Hermes and inprocess backend

Source: https://hermescache.readthedocs.io/en/latest/design.html

Shows how to cache a function using Hermes with the inprocess backend. The cache key is derived from the callable and arguments, and the return value is stored. The example prints the backend dump showing two cache entries with argument hashes.

```python
import hermes.backend.inprocess


cache = hermes.Hermes(hermes.backend.inprocess.Backend)

@cache
def foo(a, b):
  return a * b

foo(2, 2)
foo(2, 4)

print(cache.backend.dump())
#  {
#    'cache:entry:foo:bNapzUm_P8fjh8lhIWYgkg': 8,
#    'cache:entry:foo:JjwE0zQhMRt_5lfwNNPk1Q': 4
#                            ↑
#                      argument hash
#  }
```

--------------------------------

### Synchronous Hermes caching example

Source: https://hermescache.readthedocs.io/en/latest/asyncio.html

Shows the basic synchronous usage of Hermes with a Redis backend. The function fn is cached and called synchronously. This is the baseline for understanding the asynchronous problem.

```python
import hermes.backend.redis


cache = hermes.Hermes(hermes.backend.redis.Backend)

@cache
def fn(a):
  return a + 1

def main():
  fn(1)
```

--------------------------------

### Tagging cache entries with Hermes

Source: https://hermescache.readthedocs.io/en/latest/design.html

Demonstrates how to tag cache entries using the 'tags' parameter. The example shows the backend dump with tag entries and a cache entry that includes a tag hash in its key. This enables batch invalidation by removing the tag entry.

```python
import hermes.backend.inprocess


cache = hermes.Hermes(hermes.backend.inprocess.Backend)

@cache(tags = ('tag1', 'tag2'))
def foo(a, b):
  return a * b

foo(2, 2)

print(cache.backend.dump())
#  {
#    'cache:tag:tag1': 'SeL9JQMnT-_4jRN1nxeoeg',
#    'cache:tag:tag2': 'n_OXAKlSjiz5zK5iAEe7zA',
#    'cache:entry:foo:JjwE0zQhMRt_5lfwNNPk1Q:h_C-2mB3kWNNrA4r7byxNA': 4
#                                                      ↑
#                                                   tag hash
#  }
```

--------------------------------

### Custom Serialiser for alternative serialisation

Source: https://hermescache.readthedocs.io/en/latest/customisation.html

Replace the default serialiser with a custom one using msgpack. The example shows setting the serialiser on the cache's mangler.

```python
cache = hermes.Hermes(hermes.backend.redis.Backend)

# use another serialisation algorithm
cache.mangler.serialiser = hermes.Serialiser(
  msgpack.dumps, lambda b: msgpack.loads(b, strict_map_key = False)
)
```

--------------------------------

### Usage example for Cached descriptor

Source: https://hermescache.readthedocs.io/en/report/htmlcov/z_29e638db6e54f801___init___py.html

Shows how to use the Cached descriptor by decorating a method with the cache instance. The last attribute access triggers the descriptor's __get__ method.

```python
cache = hermes.Hermes()

class Model:

    @cache
    def calc(self):
        return 42

m = Model()
m.calc
```

--------------------------------

### Descriptor protocol example with Cached decorator

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Shows how the Cached decorator implements the non-data descriptor protocol. When an instance method is decorated, attribute access triggers __get__ and returns a bound copy. The example creates a Hermes cache, decorates a method, and accesses it on an instance.

```python
cache = hermes.Hermes()

class Model:

  @cache
  def calc(self):
    return 42

m = Model()
m.calc
```

--------------------------------

### Example of cache key clash for dynamically defined functions

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Shows two dynamically defined functions with the same name 'f' in the same module, causing cache keys to clash and both calls to return 3. Use a custom 'key' function to avoid this.

```python
def createF1():
    @cache
    def f(a, b):
        return a + b
    return f

def createF2():
    @cache
    def f(a, b):
        return a * b
    return f

print(createF1()(1, 2))
print(createF2()(1, 2))
```

--------------------------------

### Asynchronous Hermes caching example

Source: https://hermescache.readthedocs.io/en/latest/asyncio.html

Shows the same Hermes API applied to an async coroutine function. The coroutine awaits a cached synchronous function and uses asyncio.sleep. This illustrates the mixed execution model problem.

```python
import asyncio

import hermes.backend.redis


cache = hermes.Hermes(hermes.backend.redis.Backend)

@cache
def fn(a):
  return a + 1

@cache
async def coro(a):
  await asyncio.sleep(fn(1))
  return a + 2

async def main():
  await coro(1)
```

--------------------------------

### Custom Compressor for compression settings

Source: https://hermescache.readthedocs.io/en/latest/customisation.html

Shows how to disable compression by setting compressor to None, and how to use a custom compressor with snappy. The Compressor constructor takes compress, decompress, decompressError, and an optional threshold.

```python
cache = hermes.Hermes(hermes.backend.redis.Backend)

# disable compression
cache.mangler.compressor = None

# use another compression algorithm
cache.mangler.compressor = hermes.Compressor(
  snappy.compress, snappy.decompress, snappy.UncompressError, 32
)
```

--------------------------------

### AsyncLock.__enter__

Source: https://hermescache.readthedocs.io/en/latest/reference.html

No-op context manager implementation used by hermes.Cached for synchronous code.

```APIDOC
## AsyncLock.__enter__

### Description
No-op context manager implementation.

### Method
__enter__

### Notes
Used by `hermes.Cached` for synchronous code.
```

--------------------------------

### Backend class with __init__ and lock method

Source: https://hermescache.readthedocs.io/en/report/htmlcov/z_0a3d1c31add3250f_redis_py.html

The Backend class extends AbstractBackend and implements a Redis backend. Its __init__ method accepts a mangler, host, password, port, db, lockconf, and additional kwargs, creating a redis.StrictRedis client and storing the lock configuration. The lock method returns a Lock instance using the mangled key name and the client.

```python
class Backend(AbstractBackend):
    '''Redis backend implementation.'''

    client: redis.StrictRedis
    '''Redis client.'''

    _lockconf: dict
    '''Lock config.'''

    def __init__(
        self,
        mangler,
        *,
        host: str = 'localhost',
        password: Optional[str] = None,
        port: int = 6379,
        db: int = 0,
        lockconf: Optional[dict] = None,
        **kwargs
    ):
        super().__init__(mangler)

        # Redis client creates a pool that connects lazily
        self.client = redis.StrictRedis(host, port, db, password, **kwargs)

        self._lockconf = lockconf or {}

    def lock(self, key: str) -> Lock:
        return Lock(self.mangler.nameLock(key), self.client, **self._lockconf)
```

--------------------------------

### hermes.backend.inprocess.Backend

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Simple in-process dictionary-based backend implementation.

```APIDOC
## hermes.backend.inprocess.Backend

### Description
Simple in-process dictionary-based backend implementation.

### Constructor
`Backend(mangler, *args)`

### Parameters
- **mangler** - The key mangler to use.
- **\*args** - Additional positional arguments.
```

--------------------------------

### hermes.CachedCoro.__call__

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Get the value of the wrapped coroutine function's coroutine.

```APIDOC
## hermes.CachedCoro.__call__

### Description
Get the value of the wrapped coroutine function's coroutine.

### Method
__call__ (async)

### Parameters
- *args - positional arguments passed to the wrapped coroutine function
- **kwargs - keyword arguments passed to the wrapped coroutine function

### Returns
The coroutine of the wrapped coroutine function.
```

--------------------------------

### hermes.Cached.__call__

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Get the value of the wrapped callable. This method is called when the decorated function is invoked.

```APIDOC
## hermes.Cached.__call__

### Description
Get the value of the wrapped callable.

### Method
__call__

### Parameters
- *args - positional arguments passed to the wrapped callable
- **kwargs - keyword arguments passed to the wrapped callable

### Returns
The value returned by the wrapped callable.
```

--------------------------------

### hermes.backend.inprocess.AsyncBackend

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Simple in-process dictionary-based backend for asyncio programs.

```APIDOC
## hermes.backend.inprocess.AsyncBackend

### Description
Simple in-process dictionary-based backend for `asyncio` programs.

### Constructor
`AsyncBackend(mangler, *args)`

### Parameters
- **mangler** - The key mangler to use.
- **\*args** - Additional positional arguments.
```

--------------------------------

### Cache class __init__ method

Source: https://hermescache.readthedocs.io/en/report/htmlcov/z_29e638db6e54f801___init___py.html

Constructor for the Cache class, initializing TTL, mangler, and backend. Warns if backend options are passed with an instance.

```python
def __init__(
    self,
    backend: Union[Type[AbstractBackend], AbstractBackend] = AbstractBackend,
    *,
    mangler: Optional[Mangler] = None,
    cachedfactory: Callable[..., Cached] = cachedfactory,
    ttl: int = 3600,
    **backendconf
):
    self.ttl = ttl

    mangler = mangler or Mangler()
    assert isinstance(mangler, Mangler)
    self.mangler = mangler

    if isinstance(backend, AbstractBackend):
        if backendconf:
            warnings.warn('Backend options ignored because backend instance is passed')
```

--------------------------------

### BaseBackend.dump

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Dumps the cache entries as a dictionary.

```APIDOC
## BaseBackend.dump

### Description
Dumps the cache entries as a dictionary.

### Method
dump

### Signature
dump()

### Parameters
None

### Returns
Dict[str, Any]
```

--------------------------------

### Backend.dump

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Dumps the cache entries as a dictionary.

```APIDOC
## Backend.dump

### Description
Dumps the cache entries as a dictionary.

### Method
dump

### Signature
dump()

### Parameters
None

### Returns
Dict[str, Any]
```

--------------------------------

### Memory overhead of stale cache entries after invalidation

Source: https://hermescache.readthedocs.io/en/latest/design.html

Shows the memory overhead of tag entries and stale cache entries. After calling cache.clean(['tag1']), the tag entry is recreated and the old cache entry remains as garbage. The example prints the backend dump before and after cleaning.

```python
import hermes.backend.inprocess


cache = hermes.Hermes(hermes.backend.inprocess.Backend)

@cache(tags = ('tag1', 'tag2'))
def foo(a, b):
  return a * b

foo(2, 2)

print(cache.backend.dump())
#  {
#    'cache:tag:tag1': 'Z_t4-2QfjwvYUc_d75WJgw',
#    'cache:tag:tag2': 'M_2pg1-dfS_8OM1Dnd4mXw',
#    'cache:entry:foo:JjwE0zQhMRt_5lfwNNPk1Q:ZuT3KKj6gttXtU01-JSbwQ': 4
#  }

cache.clean(['tag1'])
foo(2, 2)

print(cache.backend.dump())
#  {
#      recreated tag entry
#             ↓
#    'cache:tag:tag1': 'TAuY_hhl0a22Nm7P_dWQRA',
#    'cache:tag:tag2': 'M_2pg1-dfS_8OM1Dnd4mXw',
#    'cache:entry:foo:JjwE0zQhMRt_5lfwNNPk1Q:St3ZHOzerXZxN0qkzXcLVw': 4,
#    'cache:entry:foo:JjwE0zQhMRt_5lfwNNPk1Q:ZuT3KKj6gttXtU01-JSbwQ': 4
#             ↑
#        garbage entry
#  }
```

--------------------------------

### AsyncLock.__exit__

Source: https://hermescache.readthedocs.io/en/latest/reference.html

No-op context manager implementation used by hermes.Cached for synchronous code.

```APIDOC
## AsyncLock.__exit__

### Description
No-op context manager implementation.

### Method
__exit__

### Parameters
- **args** - Required - Arguments passed to the exit method.

### Notes
Used by `hermes.Cached` for synchronous code.
```

--------------------------------

### BaseBackend.load

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Loads cache entries by key or iterable of keys. For multiple keys, returns a dictionary excluding absent keys.

```APIDOC
## BaseBackend.load

### Description
Loads cache entries by key or iterable of keys. For multiple keys, returns a dictionary excluding absent keys.

### Method
load

### Signature
load(keys)

### Parameters
- **keys** (str | Iterable[str]) - Required - Key or iterable of keys to load.

### Returns
Any | Dict[str, Any] | None
```

--------------------------------

### AsyncBackend.clean

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Purges the backend storage.

```APIDOC
## AsyncBackend.clean

### Description
Purge the backend storage.

### Method
clean
```

--------------------------------

### Run cache.clean in asyncio thread pool

Source: https://hermescache.readthedocs.io/en/latest/asyncio.html

Shows how to run the synchronous Hermes.clean method in the default asyncio thread pool using loop.run_in_executor, as clean can be slow depending on the backend.

```python
import asyncio

loop = asyncio.get_event_loop()
await loop.run_in_executor(None, cache.clean, ['pypi'])
```

--------------------------------

### hermes.backend.AbstractBackend

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Base backend class and no-op implementation. Users can subclass this to create custom cache backends. Provides methods for locking, saving, loading, removing, and cleaning cache entries.

```APIDOC
## Class: hermes.backend.AbstractBackend

### Description
Base backend class. It's also the no-op implementation. Subclass this to implement a custom cache backend.

### Constructor
`AbstractBackend(mangler)`

#### Parameters
- **mangler** (Mangler) - Required - Key manager responsible for creating keys, hashing and serialisation.

### Attributes
- **mangler** (Mangler) - Key manager responsible for creating keys, hashing and serialisation.

### Methods

#### lock(key)
Create lock object for the key.

##### Parameters
- **key** (str) - Required - The cache key.

##### Return Type
- AbstractLock

#### save(mapping, *, ttl=None)
Save cache entry.

##### Parameters
- **mapping** (Dict[str, Any]) - Required - `key`-`value` mapping for a bulk save.
- **ttl** (int | None) - Optional - Cache entry time-to-live.

#### load(keys)
Load cache entry(ies). Note, when handling a multiple key call, absent value keys should be excluded from resulting dictionary.

##### Parameters
- **keys** (str | Iterable[str]) - Required - Key or keys to load.

##### Return Type
- Any | Dict[str, Any] | None

#### remove(keys)
Remove given keys.

##### Parameters
- **keys** (str | Iterable[str]) - Required - Key or keys to remove.

#### clean()
Purge the backend storage.

```

--------------------------------

### AsyncBackend.save

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Saves cache entries in bulk. Accepts a mapping of keys to values and an optional TTL.

```APIDOC
## AsyncBackend.save

### Description
Save cache entry.

### Method
save

### Parameters
- **mapping** (Dict[str, Any]) - Required - key-value mapping for a bulk save.
- **ttl** (int | None) - Optional - Cache entry time-to-live.
```

--------------------------------

### hermes.backend.redis.Backend

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Redis backend implementation for Hermes Cache.

```APIDOC
## hermes.backend.redis.Backend

### Description
Redis backend implementation for Hermes Cache.

### Constructor
`Backend(mangler, *args, **kwargs)`

### Parameters
- **mangler** - The key mangler to use.
- **\*args** - Additional positional arguments.
- **\*\*kwargs** - Additional keyword arguments.
```

--------------------------------

### Backend.save

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Saves cache entries in bulk with optional TTL. Overrides BaseBackend.save.

```APIDOC
## Backend.save

### Description
Saves cache entries in bulk with optional TTL. Overrides BaseBackend.save.

### Method
save

### Signature
save(mapping, *, ttl=None)

### Parameters
- **mapping** (Dict[str, Any]) - Required - key-value mapping for a bulk save.
- **ttl** (int | None) - Optional - Cache entry time-to-live.

### Returns
None
```

--------------------------------

### hermes.backend.memcached.Backend

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Memcached backend implementation for Hermes Cache.

```APIDOC
## hermes.backend.memcached.Backend

### Description
Memcached backend implementation for Hermes Cache.

### Constructor
`Backend(mangler, *args)`

### Parameters
- **mangler** - The key mangler to use.
- **\*args** - Additional positional arguments.
```

--------------------------------

### Hermes Constructor

Source: https://hermescache.readthedocs.io/en/report/htmlcov/z_29e638db6e54f801___init___py.html

Creates a Hermes cache instance. The backend argument is required, while mangler, cachedfactory, and ttl are optional. If backend is omitted, a no-op backend is used.

```APIDOC
## Hermes Constructor

### Description
Creates a Hermes cache instance. The backend argument is required, while mangler, cachedfactory, and ttl are optional. If backend is omitted, a no-op backend is used.

### Method
Constructor

### Signature
`Hermes(backend, mangler=None, cachedfactory=None, ttl=None)`

### Parameters
- **backend** (type) - Required - The cache backend class or instance.
- **mangler** (type) - Optional - Typically a subclass of mangler instance.
- **cachedfactory** (type) - Optional - A cache-point factory for functions and coroutines.
- **ttl** (type) - Optional - Default cache entry time-to-live.

### Usage Example
```python
import hermes.backend.redis

cache = hermes.Hermes(
    hermes.backend.redis.Backend, ttl = 600, host = 'localhost', db = 1
)

@cache
def foo(a, b):
    return a * b

class Example:

    @cache(tags = ('math', 'power'), ttl = 1200)
    def bar(self, a, b):
        return a ** b

    @cache(
        tags = ('math', 'avg'),
        key = lambda fn, *args, **kwargs: 'avg:{0}:{1}'.format(*args),
    )
    def baz(self, a, b):
        return (a + b) / 2.0

print(foo(2, 333))

example = Example()
print(example.bar(2, 10))
print(example.baz(2, 10))
```
```

--------------------------------

### nameEntry docstring with cache key representation

Source: https://hermescache.readthedocs.io/en/report/htmlcov/z_29e638db6e54f801___init___py.html

Docstring for the nameEntry method explaining how callable fn is represented in the cache key: MethodType as (module, class, method), FunctionType as (module, function), and other callables with __name__ as (module, object).

```python
def nameEntry(self, fn: Callable, *args, **kwargs) -> str:
    '''
    Return cache key for given callable and its positional and
    keyword arguments.

    Note how callable, ``fn``, is represented in the cache key:

    1) a ``types.MethodType`` instance -> names of
       ``(module, class, method)``
    2) a ``types.FunctionType`` instance -> names of
       ``(module, function)``
    3) other callalbe objects with ``__name__`` -> name of
       ``(module, object)``

    This means that if two function are defined dynamically in the
    same module with same names, like::
```

--------------------------------

### BaseBackend.clean

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Purges the backend storage, removing all cache entries.

```APIDOC
## BaseBackend.clean

### Description
Purges the backend storage, removing all cache entries.

### Method
clean

### Signature
clean()

### Parameters
None

### Returns
None
```

--------------------------------

### Backend.clean

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Purges the backend storage, removing all cache entries.

```APIDOC
## Backend.clean

### Description
Purges the backend storage, removing all cache entries.

### Method
clean

### Signature
clean()

### Parameters
None

### Returns
None
```

--------------------------------

### Custom Compressor

Source: https://hermescache.readthedocs.io/en/latest/customisation.html

Shows how to disable compression or use a different compression algorithm by setting the compressor attribute on the mangler.

```APIDOC
## Custom Compressor

### Description
Disable compression or use a different compression algorithm by setting the compressor attribute on the mangler.

### Usage
```python
cache = hermes.Hermes(hermes.backend.redis.Backend)

# disable compression
cache.mangler.compressor = None

# use another compression algorithm
cache.mangler.compressor = hermes.Compressor(
    snappy.compress, snappy.decompress, snappy.UncompressError, 32
)
```
```

--------------------------------

### BaseBackend.save

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Saves cache entries in bulk using a key-value mapping. Optionally accepts a TTL for the entries.

```APIDOC
## BaseBackend.save

### Description
Saves cache entries in bulk using a key-value mapping. Optionally accepts a TTL for the entries.

### Method
save

### Signature
save(mapping, *, ttl=None)

### Parameters
- **mapping** (Dict[str, Any]) - Required - key-value mapping for a bulk save.
- **ttl** (int | None) - Optional - Cache entry time-to-live.

### Returns
None
```

--------------------------------

### Lock class with acquire and release methods

Source: https://hermescache.readthedocs.io/en/report/htmlcov/z_0a3d1c31add3250f_redis_py.html

The Lock class uses a Redis client to implement a distributed lock. The acquire method attempts to set a key with the value 'locked' using the nx and ex options, returning True on success. If wait is False, it returns False immediately; otherwise, it sleeps for the configured sleep interval and retries. The release method deletes the key.

```python
def acquire(self, wait = True):
    while True:
        if self.client.set(self.key, 'locked', nx = True, ex = self.timeout):
            return True
        elif not wait:
            return False
        else:
            time.sleep(self.sleep)

def release(self):
    self.client.delete(self.key)
```

--------------------------------

### Custom Serialiser

Source: https://hermescache.readthedocs.io/en/latest/customisation.html

Shows how to replace the default serialisation algorithm by assigning a new Serialiser instance to the cache's mangler.

```APIDOC
## Custom Serialiser

### Description
Replace the default serialisation algorithm by assigning a new Serialiser instance to the cache's mangler.

### Usage
```python
cache = hermes.Hermes(hermes.backend.redis.Backend)

# use another serialisation algorithm
cache.mangler.serialiser = hermes.Serialiser(
    msgpack.dumps, lambda b: msgpack.loads(b, strict_map_key = False)
)
```
```

--------------------------------

### AsyncBackend.lock

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Creates a lock object for the given key. Returns an AsyncLock instance.

```APIDOC
## AsyncBackend.lock

### Description
Create lock object for the key.

### Method
lock

### Parameters
- **key** (str) - Required - The key for which to create the lock.

### Return Type
AsyncLock
```

--------------------------------

### Custom Mangler

Source: https://hermescache.readthedocs.io/en/latest/customisation.html

Shows how to create a custom Mangler subclass to override the hash algorithm used for cache keys.

```APIDOC
## Custom Mangler

### Description
Create a custom Mangler subclass to override the hash algorithm used for cache keys.

### Usage
```python
class CustomMangler(hermes.Mangler):
    def hash(self, value):
        return str(hash(value))

cache = hermes.Hermes(
    hermes.backend.redis.Backend, mangler = CustomMangler()
)
```
```

--------------------------------

### hermes.Compressor

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Compression delegate. Holds compress and decompress callables, decompression error types, and minimum compression length.

```APIDOC
## hermes.Compressor

### Description
Compression delegate. Holds compress and decompress callables, decompression error types, and minimum compression length.

### Constructor Parameters
- compress (Callable[[bytes], bytes]) - Required - Function to compress serialised cache value.
- decompress (Callable[[bytes], bytes]) - Required - Function to decompress serialised cache value.
- decompressError (Type[Exception] | Tuple[Type[Exception], ...]) - Required - Exception type(s) that indicate uncompressed payload.
- compressMinLength (int) - Optional - Minimum length for compression to be applied. Default is 0.

### Attributes
- compress (Callable[[bytes], bytes]) - Compress serialised cache value.
- decompress (Callable[[bytes], bytes]) - Decompress serialised cache value.
- decompressError (Type[Exception] | Tuple[Type[Exception], ...]) - Decompression error(s) that indicate uncompressed payload.
- compressMinLength (int) - Minimum length for compression.
```

--------------------------------

### Backend.lock

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Creates a lock object for the given key.

```APIDOC
## Backend.lock

### Description
Creates a lock object for the given key.

### Method
lock

### Signature
lock(key)

### Parameters
- **key** (str) - Required - The key for which to create a lock.

### Returns
Lock
```

--------------------------------

### Lock.acquire

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Acquires the reentrant lock.

```APIDOC
## Lock.acquire

### Description
Acquires the reentrant lock.

### Method
acquire

### Signature
acquire(wait=True)

### Parameters
- **wait** (bool) - Optional - Whether to wait for the lock if it is held. Defaults to True.

### Returns
None
```

--------------------------------

### Hermes

Source: https://hermescache.readthedocs.io/en/latest/reference.html

The Hermes class is the main cache facade providing a unified interface to the caching system.

```APIDOC
## Hermes

### Description
The Hermes class is the cache façade, providing the main entry point for caching operations.

### Constructor
`Hermes(backend=None, mangler=None, cachedfactory=None, ttl=None)`

### Parameters
- **backend** (optional) - The backend to use for caching.
- **mangler** (optional) - The key mangler to use.
- **cachedfactory** (optional) - The cached factory to use.
- **ttl** (optional) - Default time-to-live for cached items.
```

--------------------------------

### AsyncLock.acquire

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Acquires the asynchronous lock. Used by CachedCoro for asynchronous code.

```APIDOC
## AsyncLock.acquire

### Description
Acquire the asynchronous lock.

### Method
acquire

### Parameters
- **wait** (bool) - Optional - Whether to wait for the lock. Defaults to True.

### Return Type
bool

### Notes
Used by `CachedCoro` for asynchronous code.
```

--------------------------------

### hermes.backend.redis.Backend

Source: https://hermescache.readthedocs.io/en/latest/reference.html

Redis backend implementation for Hermes Cache. Provides methods to save, load, remove, and clean cache entries, and to create lock objects.

```APIDOC
## Class: hermes.backend.redis.Backend

### Description
Redis backend implementation for Hermes Cache.

### Constructor
`Backend(mangler, *, host='localhost', password=None, port=6379, db=0, lockconf=None, **kwargs)`

#### Parameters
- **mangler** (callable) - Required - Mangler function.
- **host** (str) - Optional - Redis host. Default: 'localhost'.
- **password** (str | None) - Optional - Redis password.
- **port** (int) - Optional - Redis port. Default: 6379.
- **db** (int) - Optional - Redis database index. Default: 0.
- **lockconf** (dict | None) - Optional - Lock configuration.
- **kwargs** - Additional keyword arguments.

### Attributes
- **client** (Redis) - Redis client.

### Methods

#### lock(key)
Create lock object for the key.

**Parameters:**
- **key** (str) - Required - Key for the lock.

**Return type:** Lock

#### save(mapping, *, ttl=None)
Save cache entry.

**Parameters:**
- **mapping** (Dict[str, Any]) - Required - `key`-`value` mapping for a bulk save.
- **ttl** (int | None) - Optional - Cache entry time-to-live.

#### load(keys)
Load cache entry(ies). Note, when handling a multiple key call, absent value keys should be excluded from resulting dictionary.

**Parameters:**
- **keys** (str | Iterable[str]) - Required - Key or keys to load.

**Return type:** Any | Dict[str, Any] | None

#### remove(keys)
Remove given keys.

**Parameters:**
- **keys** (str | Iterable[str]) - Required - Key or keys to remove.

#### clean()
Purge the backend storage.
```
Tokens:
Raw