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:

_images/set_operation_flow.png

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)[source]

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)[source]

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, redis 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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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, redis 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)[source]

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)[source]

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, redis 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

Cache

class aiocache.Cache(cache_class=<class 'aiocache.backends.memory.SimpleMemoryCache'>, **kwargs)[source]

This class is just a proxy to the specific cache implementations like aiocache.SimpleMemoryCache, aiocache.RedisCache and aiocache.MemcachedCache. It is the preferred method of instantiating new caches over using the backend specific classes.

You can instatiate a new one using the cache_type attribute like:

>>> from aiocache import Cache
>>> Cache(Cache.REDIS)
RedisCache (127.0.0.1:6379)

If you don’t specify anything, Cache.MEMORY is used.

Only Cache.MEMORY, Cache.REDIS and Cache.MEMCACHED types are allowed. If the type passed is invalid, it will raise a aiocache.exceptions.InvalidCacheType exception.

MEMORY

alias of SimpleMemoryCache

classmethod from_url(url)[source]

Given a resource uri, return an instance of that cache initialized with the given parameters. An example usage:

>>> from aiocache import Cache
>>> Cache.from_url('memory://')
<aiocache.backends.memory.SimpleMemoryCache object at 0x1081dbb00>

a more advanced usage using queryparams to configure the cache:

>>> from aiocache import Cache
>>> cache = Cache.from_url('redis://localhost:10/1?pool_max_size=1')
>>> cache
RedisCache (localhost:10)
>>> cache.db
1
>>> cache.pool_max_size
1
Parameters:

url – string identifying the resource uri of the cache to connect to

RedisCache

SimpleMemoryCache

class aiocache.SimpleMemoryCache(serializer=None, **kwargs)[source]
Memory cache implementation with the following components as defaults:

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.

MemcachedCache