Caches

You can use different caches according to your needs. All the caches implement the same interface.

Caches are always working together with a serializer which transforms data when storing and retrieving from the backend. It may also contain plugins that are able to enrich the behavior of your cache (like adding metrics, logs, etc).

This is the flow of the set command:

Let’s go with a more specific case. Let’s pick Redis as the cache with namespace “test” and PickleSerializer as the serializer:

1. We receive set("key", "value").

2. Hook pre_set of all attached plugins (none by default) is called.

3. “key” will become “test:key” when calling build_key.

4. “value” will become an array of bytes when calling serializer.dumps because of PickleSerializer.

5. the byte array is stored together with the key using set cmd in Redis.

6. Hook post_set of all attached plugins is called.

By default, all commands are covered by a timeout that will trigger an asyncio.TimeoutError in case of timeout. Timeout can be set at instance level or when calling the command.

The supported commands are:

• add

• get

• set

• multi_get

• multi_set

• delete

• exists

• increment

• expire

• clear

• raw

If you feel a command is missing here do not hesitate to open an issue

BaseCache

class aiocache.base.BaseCache(serializer: BaseSerializer | None = None, plugins: ~typing.List[BasePlugin] | None = None, namespace: str = '', key_builder: ~typing.Callable[[str, str], str] = <function BaseCache.<lambda>>, timeout: float | None = 5, ttl: float | None = None)

Base class that agregates the common logic for the different caches that may exist. Cache related available options are:

Parameters:

• serializer – obj derived from aiocache.serializers.BaseSerializer. Default is aiocache.serializers.StringSerializer.

• plugins – list of aiocache.plugins.BasePlugin derived classes. Default is empty list.

• namespace – string to use as default prefix for the key used in all operations of the backend. Default is an empty string, “”.

• key_builder – alternative callable to build the key. Receives the key and the namespace as params and should return a string that can be used as a key by the underlying backend.

• timeout – int or float in seconds specifying maximum timeout for the operations to last. By default its 5. Use 0 or None if you want to disable it.

• ttl – int the expiration time in seconds to use as a default in all operations of the backend. It can be overriden in the specific calls.

async add(key, value, ttl=<object object>, dumps_fn=None, namespace=None, _conn=None)

Stores the value in the given key with ttl if specified. Raises an error if the key already exists.

Parameters:

• key – str

• value – obj

• ttl – int the expiration time in seconds. Due to memcached restrictions if you want compatibility use int. In case you need miliseconds, valkey and memory support float ttls

• dumps_fn – callable alternative to use as dumps function

• namespace – str alternative namespace to use

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

True if key is inserted

Raises:

• ValueError if key already exists

• asyncio.TimeoutError if it lasts more than self.timeout

async clear(namespace=None, _conn=None)

Clears the cache in the cache namespace. If an alternative namespace is given, it will clear those ones instead.

Parameters:

• namespace – str alternative namespace to use

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

True

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

async close(*args, _conn=None, **kwargs)

Perform any resource clean up necessary to exit the program safely. After closing, cmd execution is still possible but you will have to close again before exiting.

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

async delete(key, namespace=None, _conn=None)

Deletes the given key.

Parameters:

• key – Key to be deleted

• namespace – str alternative namespace to use

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

int number of deleted keys

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

async exists(key, namespace=None, _conn=None)

Check key exists in the cache.

Parameters:

• key – str key to check

• namespace – str alternative namespace to use

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

True if key exists otherwise False

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

async expire(key, ttl, namespace=None, _conn=None)

Set the ttl to the given key. By setting it to 0, it will disable it

Parameters:

• key – str key to expire

• ttl – int number of seconds for expiration. If 0, ttl is disabled

• namespace – str alternative namespace to use

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

True if set, False if key is not found

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

async get(key, default=None, loads_fn=None, namespace=None, _conn=None)

Get a value from the cache. Returns default if not found.

Parameters:

• key – str

• default – obj to return when key is not found

• loads_fn – callable alternative to use as loads function

• namespace – str alternative namespace to use

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

obj loaded

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

async increment(key, delta=1, namespace=None, _conn=None)

Increments value stored in key by delta (can be negative). If key doesn’t exist, it creates the key with delta as value.

Parameters:

• key – str key to check

• delta – int amount to increment/decrement

• namespace – str alternative namespace to use

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

Value of the key once incremented. -1 if key is not found.

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

Raises:

TypeError if value is not incrementable

async multi_get(keys, loads_fn=None, namespace=None, _conn=None)

Get multiple values from the cache, values not found are Nones.

Parameters:

• keys – list of str

• loads_fn – callable alternative to use as loads function

• namespace – str alternative namespace to use

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

list of objs

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

async multi_set(pairs, ttl=<object object>, dumps_fn=None, namespace=None, _conn=None)

Stores multiple values in the given keys.

Parameters:

• pairs – list of two element iterables. First is key and second is value

• ttl – int the expiration time in seconds. Due to memcached restrictions if you want compatibility use int. In case you need miliseconds, valkey and memory support float ttls

• dumps_fn – callable alternative to use as dumps function

• namespace – str alternative namespace to use

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

True

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

async raw(command, *args, _conn=None, **kwargs)

Send the raw command to the underlying client. Note that by using this CMD you will lose compatibility with other backends.

Due to limitations with aiomcache client, args have to be provided as bytes. For rest of backends, str.

Parameters:

• command – str with the command.

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

whatever the underlying client returns

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

async set(key, value, ttl=<object object>, dumps_fn=None, namespace=None, _cas_token=None, _conn=None)

Stores the value in the given key with ttl if specified

Parameters:

• key – str

• value – obj

• ttl – int the expiration time in seconds. Due to memcached restrictions if you want compatibility use int. In case you need miliseconds, valkey and memory support float ttls

• dumps_fn – callable alternative to use as dumps function

• namespace – str alternative namespace to use

• timeout – int or float in seconds specifying maximum timeout for the operations to last

Returns:

True if the value was set

Raises:

asyncio.TimeoutError if it lasts more than self.timeout

RedisCache

SimpleMemoryCache

class aiocache.SimpleMemoryCache(**kwargs)

Memory cache implementation with the following components as defaults:

• serializer: aiocache.serializers.NullSerializer

• plugins: None

• backend: dict

Config options are:

Parameters:

• serializer – obj derived from aiocache.serializers.BaseSerializer.

• plugins – list of aiocache.plugins.BasePlugin derived classes.

• namespace – string to use as default prefix for the key used in all operations of the backend. Default is an empty string, “”.

• timeout – int or float in seconds specifying maximum timeout for the operations to last. By default, its 5.

• maxsize – int maximum number of keys to store (None for unlimited)

MemcachedCache

class aiocache.backends.memcached.MemcachedCache(host='127.0.0.1', port=11211, pool_size=2, **kwargs)

Memcached cache implementation with the following components as defaults:

• serializer: aiocache.serializers.JsonSerializer

• plugins: []

Config options are:

Parameters:

• serializer – obj derived from aiocache.serializers.BaseSerializer.

• plugins – list of aiocache.plugins.BasePlugin derived classes.

• namespace – string to use as default prefix for the key used in all operations of the backend. Default is an empty string, “”.

• timeout – int or float in seconds specifying maximum timeout for the operations to last. By default its 5.

• endpoint – str with the endpoint to connect to. Default is 127.0.0.1.

• port – int with the port to connect to. Default is 11211.

• pool_size – int size for memcached connections pool. Default is 2.

Third-party caches

Additional cache backends are available through other libraries.

DynamoDBCache

aiocache-dynamodb provides support for DynamoDB.

class aiocache_dynamodb.DynamoDBCache(table_name: str, bucket_name: str | None = None, serializer: BaseSerializer | None = None, namespace: str = '', key_builder: Callable[[str, str], str] | None = None, endpoint_url: str | None = None, region_name: str = 'us-east-1', aws_access_key_id: str | None = None, aws_secret_access_key: str | None = None, key_column: str = 'cache_key', value_column: str = 'cache_value', ttl_column: str = 'ttl', dynamodb_client: DynamoDBClient | None = None, s3_client: S3Client | None = None, **kwargs: Any)

DynamoDB cache implementation with the following components as defaults:

• serializer: aiocache.serializers.StringSerializer

• plugins: None

Config options are:

Parameters:

• table_name (str) – The name of the DynamoDB table to use for caching.

• bucket_name (str | None) – Optional name of the S3 bucket in case S3 extension for larger items is needed.

• serializer (aiocache.serializers.BaseSerializer) –

  obj derived from aiocache.serializers.BaseSerializer, used to serialize and deserialize values. Default is

  aiocache.serializers.StringSerializer.

• plugins (list of aiocache.plugins.BasePlugin) – list of aiocache.plugins.BasePlugin derived classes. Default is an empty list.

• namespace (str, optional) – string to use as default prefix for the key used in all operations of the backend. Default is an empty string, “”.

• timeout (int or float, optional) – int or float in seconds specifying maximum timeout for the operations to last. Defaults to 5.

• endpoint_url (str, optional) – The endpoint URL to use for the DynamoDB client.

• region_name (str, optional) – The region name to use for the DynamoDB client. Defaults to “us-east-1”.

• aws_access_key_id (str, optional) – The AWS access key ID to use for the DynamoDB client.

• aws_secret_access_key (str, optional) – The AWS secret access key to use for the DynamoDB client.

• key_column (str, optional) – The name of the key column in the DynamoDB table. Defaults to “cache_key”.

• value_column (str, optional) – The name of the value column in the DynamoDB table. Defaults to “cache_value”.

• ttl_column (str, optional) – The name of the TTL column in the DynamoDB table. Defaults to “ttl”.

• key_builder (callable, optional) – A callable that takes a key and namespace and returns a formatted key. Default is a lambda function that formats the key with the namespace.

• dynamodb_client (DynamoDBClient, optional) – The DynamoDB client to use. If not provided, a new client will be created lazily on first call or on __aenter__. If provided, it should be an instance of aiobotocore.client.AioBaseClient that has been initialized.

• s3_client (S3Client, optional) – The S3 client to use. If not provided, a new client will be created lazily on first call or on __aenter__. If provided, it should be an instance of aiobotocore.client.AioBaseClient that has been initialized.

• kwargs (dict, optional) – Additional keyword arguments to pass to the parent class.