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 of PickleSerializer.
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=None, plugins=None, namespace=None, key_builder=None, timeout=5, ttl=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 None
key_builder – alternative callable to build the key. Receives the key and the namespace as params and should return something that can be used as 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.

MEMCACHED¶: alias of MemcachedCache

MEMORY¶: alias of SimpleMemoryCache

REDIS¶: alias of RedisCache

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¶

class aiocache.RedisCache(serializer=None, **kwargs)[source]¶

Redis 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 None.
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 6379.
db – int indicating database to use. Default is 0.
password – str indicating password to use. Default is None.
pool_max_size – int maximum pool size for the redis connections pool. Default is None.
create_connection_timeout – int timeout for the creation of connection. Default is None

classmethod parse_uri_path(path)[source]¶

Given a uri path, return the Redis specific configuration options in that path string according to iana definition http://www.iana.org/assignments/uri-schemes/prov/redis

Parameters:: path – string containing the path. Example: “/0”
Returns:: mapping containing the options. Example: {“db”: “0”}

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 None.
timeout – int or float in seconds specifying maximum timeout for the operations to last. By default its 5.

MemcachedCache¶

class aiocache.MemcachedCache(serializer=None, **kwargs)[source]¶

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 None
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.