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:
We receive
set("key", "value")
.Hook
pre_set
of all attached plugins (none by default) is called.“key” will become “test:key” when calling
build_key
.“value” will become an array of bytes when calling
serializer.dumps
because ofPickleSerializer
.the byte array is stored together with the key using
set
cmd in Redis.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 isaiocache.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
andaiocache.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
andCache.MEMCACHED
types are allowed. If the type passed is invalid, it will raise aaiocache.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:
serializer:
aiocache.serializers.NullSerializer
plugins: None
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.