aiocache Documentation

aiocache provides several built-in backends and supports third-party extensions:

Built-in Backends:

• BaseCache: The base class for all cache implementations.
• RedisCache: Backend for Redis.
• SimpleMemoryCache: In-memory cache.
• MemcachedCache: Backend for Memcached.

Third-party Backends:

• DynamoDBCache: Provided by the aiocache-dynamodb library.

To define a custom plugin, inherit from aiocache.plugins.BasePlugin. You can override specific methods to hook into the cache lifecycle. All overridden methods must be async.

Every cache command has two types of hooks available:

1. pre_<command_name>: Executed before the command.
2. post_<command_name>: Executed after the command.

Example command hooks include pre_get, post_get, pre_set, post_set, etc.

The aiocache architecture is built on three main entities that combine to perform cache operations:

1. Backends: Determine where the data is stored (e.g., memory, Redis, Memcached).
2. Serializers: Handle the transformation of data between your Python code and the backend. This enables storing arbitrary Python objects. Supported types include:
   • StringSerializer
   • PickleSerializer
   • JsonSerializer
   • MsgPackSerializer (requires msgpack dependency)
3. Plugins: A hooks system that allows you to execute custom logic before or after each cache command.

If the built-in serializers do not meet your requirements, you can define a custom serializer class.

Note on Encoding: By default, cache backends assume they are working with str types. If your custom implementation transforms data into bytes, you must set the class attribute encoding to None.

All caches in aiocache work in conjunction with a serializer (to transform data for storage/retrieval) and optional plugins (to add behavior like metrics or logging).

When you call a command like set, the following lifecycle occurs:

1. The pre_set hook of all attached plugins is called.
2. The key is transformed via build_key (e.g., adding a namespace prefix like test:key).
3. The value is transformed via serializer.dumps (e.g., converting a Python object to bytes using PickleSerializer).
4. The transformed data is stored in the backend.
5. The post_set hook of all attached plugins is called.

By default, all commands are protected by a timeout that triggers an asyncio.TimeoutError if exceeded. Timeouts can be configured at the cache instance level or passed during individual command calls.

To isolate your tests from actual cache backends (like Redis), you can create a Mock cache by using BaseCache as the specification. This allows you to test your application logic without requiring a running cache server.

Example usage:

from aiocache import BaseCache
from unittest.mock import MagicMock

# Create a mock that follows the BaseCache interface
mock_cache = MagicMock(spec=BaseCache)

In aiocache v1, the aiocache.Cache class and cache aliases have been removed. You must now use specific cache classes directly.

Key changes:

• Direct Class Usage: Instead of using aiocache.Cache.REDIS, use aiocache.RedisCache directly.
• Decorator Usage: When using caches with decorators, ensure the cache instance is fully instantiated before passing it to the decorator, rather than passing a factory function.
• No Aliases: Cache aliases are no longer supported; always create an instance of the specific cache class you need.

Serializers transform data before it is sent to and retrieved from a cache backend. This is necessary when using backends like Redis that cannot store native Python objects directly. You can attach a serializer to a backend by passing an instance of a serializer class to the serializer argument during initialization.

from aiocache import SimpleMemoryCache
from aiocache.serializers import PickleSerializer

cache = SimpleMemoryCache(serializer=PickleSerializer())

Plugins enrich the behavior of a cache. By default, caches are initialized without plugins, but you can add them either during instantiation in the constructor or after the cache instance has been created by appending to the plugins list.

Warning: Both pre_<command_name> and post_<command_name> hooks are executed by awaiting the coroutine. Performing expensive operations within these hooks increases command latency and the risk of timeout errors. Note that if a timeout error occurs, previous actions performed by the hooks will not be rolled back.

Install the base package using pip. You can also install optional dependencies for specific backends or serializers using extras.

# Base installation
pip install aiocache

# Install with Redis support
pip install aiocache[redis]

# Install with Memcached support
pip install aiocache[memcached]

# Install with both Redis and Memcached support
pip install aiocache[redis,memcached]

# Install with MsgPack serializer support
pip install aiocache[msgpack]