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: Optional[BaseSerializer] = None, plugins: Optional[List[BasePlugin]] = None, namespace: str = '', key_builder: Callable[[str, str], str] = <function BaseCache.<lambda>>, timeout: Optional[float] = 5, ttl: Optional[float] = 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.

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

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

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

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

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

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

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

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

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

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

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

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

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 aiocache.backends.memcached.MemcachedCache

MEMORY

alias of aiocache.backends.memory.SimpleMemoryCache

REDIS

alias of aiocache.backends.redis.RedisCache

classmethod from_url(url)

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: Optional[BaseSerializer] = None, namespace: str = '', key_builder: Callable[[str, str], str] = <function RedisCache.<lambda>>, **kwargs)

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 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 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)

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)

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.

MemcachedCache

class aiocache.MemcachedCache(serializer=None, **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.