API¶

This page covers all interfaces of RC.

Base Cache System API¶

class rc.cache.BaseCache(namespace=None, serializer_cls=None, default_expire=259200, bypass_values=[])¶

Baseclass for all redis cache systems.

Parameters:	namespace – a prefix that should be added to all keys serializer_cls – the serialization class you want to use. default_expire – default expiration time that is used if no expire specified on `set()`. bypass_values – a list of return values that would be ignored by the cache decorator and won’t be cached at all.

New in version 0.3: The bypass_values parameter was added.

batch_mode()¶

Returns a context manager for cache batch mode. This is used to batch fetch results of cache decorated functions. All results returned by cache decorated function will be Promise object. This context manager runs the batch fetch and then resolves all promises in the end. Example:

results = []
with cache.batch_mode():
    for i in range(10):
        results.append(get_result(i))
results = map(lambda r: r.value, results)

Note

When you are using rc on this mode, rc is not thread safe.

cache(key_prefix=None, expire=None, include_self=False)¶

A decorator that is used to cache a function with supplied parameters. It is intended for decorator usage:

@cache.cache()
def load(name):
    return load_from_database(name)

rv = load('foo')
rv = load('foo') # returned from cache

The cache key doesn’t need to be specified, it will be created with the name of the module + the name of the function + function arguments.

Parameters:	key_prefix – this is used to ensure cache result won’t clash with another function that has the same name in this module, normally you do not need to pass this in expire – expiration time include_self – whether to include the self or cls as cache key for method or not, default to be False

Note

The function being decorated must be called with the same positional and keyword arguments. Otherwise, you might create multiple caches. If you pass one parameter as positional, do it always.

Note

Using objects as part of the cache key is possible, though it is suggested to not pass in an object instance as parameter. We perform a str() on the passed in objects so that you can provide a __str__ function that returns a identifying string for that object, the unique string will be used as part of the cache key.

Note

When a method on a class is decorated, the self or cls arguments is not included in the cache key. Starting from 0.2 you can control it with include_self. If you set include_self to True, remember to provide __str__ method for the object, otherwise you might encounter random behavior.

New in version 0.2: The include_self parameter was added.

delete(key)¶

Deletes the value for the cache key.

Parameters:	key – cache key
Returns:	Whether the key has been deleted

delete_many(*keys)¶

Deletes multiple keys.

Returns:	whether all keys has been deleted

get(key)¶

Returns the value for the cache key, otherwise None is returned.

Parameters:	key – cache key

get_client()¶: Returns the redis client that is used for cache.

get_many(*keys)¶: Returns the a list of values for the cache keys.

invalidate(func, *args, **kwargs)¶

Invalidate a cache decorated function. You must call this with the same positional and keyword arguments as what you did when you call the decorated function, otherwise the cache will not be deleted. The usage is simple:

@cache.cache()
def load(name, limit):
    return load_from_database(name, limit)

rv = load('foo', limit=5)

cache.invalidate(load, 'foo', limit=5)

Parameters:	func – decorated function to invalidate args – same positional arguments as you call the function kwargs – same keyword arguments as you call the function
Returns:	whether it is invalidated or not

set(key, value, expire=None)¶

Adds or overwrites key/value to the cache. The value expires in time seconds.

Parameters:	key – cache key value – value for the key expire – expiration time
Returns:	Whether the key has been set

set_many(mapping, expire=None)¶

Sets multiple keys and values using dictionary. The values expires in time seconds.

Parameters:	mapping – a dictionary with key/values to set expire – expiration time
Returns:	whether all keys has been set

Cache Object¶

class rc.Cache(host='localhost', port=6379, db=0, password=None, socket_timeout=None, namespace=None, serializer_cls=None, default_expire=259200, redis_options=None, bypass_values=[])¶

Uses a single Redis server as backend.

Parameters:

host – address of the Redis, this is compatible with the official Python StrictRedis cilent (redis-py).
port – port number of the Redis server.
db – db numeric index of the Redis server.
password – password authentication for the Redis server.
socket_timeout – socket timeout for the StrictRedis client.
namespace – a prefix that should be added to all keys.
serializer_cls – the serialization class you want to use. By default, it is rc.JSONSerializer.
default_expire – default expiration time that is used if no expire specified on set().
redis_options – a dictionary of parameters that are useful for setting other parameters to the StrictRedis client.
bypass_values – a list of return values that would be ignored by the cache decorator and won’t be cached at all.

New in version 0.3: The bypass_values parameter was added.

Cache Cluster Object¶

class rc.CacheCluster(hosts, namespace=None, serializer_cls=None, default_expire=259200, router_cls=None, router_options=None, pool_cls=None, pool_options=None, max_concurrency=64, poller_timeout=1.0, bypass_values=[])¶

The a redis cluster as backend.

Basic example:

cache = CacheCluster({
    0: {'port': 6379},
    1: {'port': 6479},
    2: {'port': 6579},
    3: {'port': 6679},
})

Parameters:

hosts – a dictionary of hosts that maps the host host_name to configuration parameters. The parameters are used to construct a HostConfig.
namespace – a prefix that should be added to all keys.
serializer_cls – the serialization class you want to use. By default, it is JSONSerializer.
default_expire – default expiration time that is used if no expire specified on set().
router_cls – use this to override the redis router class, default to be RedisCRC32HashRouter.
router_options – a dictionary of parameters that is useful for setting other parameters of router
pool_cls – use this to override the redis connection pool class, default to be ConnectionPool
pool_options – a dictionary of parameters that is useful for setting other parameters of pool
max_concurrency – defines how many parallel queries can happen at the same time
poller_timeout – for multi key operations we use a select loop as the parallel query implementation, use this to specify timeout for the underlying pollers (select/poll/kqueue/epoll).
bypass_values – a list of return values that would be ignored by the cache decorator and won’t be cached at all.

New in version 0.3: The bypass_values parameter was added.

Serializer¶

class rc.BaseSerializer¶

Baseclass for serializer. Subclass this to get your own serializer.

dumps(obj)¶: Dumps an object into a string for redis.

loads(string)¶: Read a serialized object from a string.

class rc.JSONSerializer¶: One serializer that uses JSON

class rc.PickleSerializer¶: One serializer that uses Pickle

Redis Router¶

The base router class provides a simple way to replace the router cls that cache cluster is using.

class rc.BaseRedisRouter(hosts)¶

Subclass this to implement your own router.

get_host_for_key(key)¶: Get host name for a certain key.

class rc.RedisCRC32HashRouter(hosts)¶: Use crc32 for hash partitioning.

class rc.RedisConsistentHashRouter(hosts)¶: Use ketama for hash partitioning.

Testing Objects¶

class rc.NullCache(*args, **kwargs)¶

Use this for unit test. This doesn’t cache.

delete(key)¶: Always return True

get(key)¶: Always return None

get_many(*keys)¶: Always return a list of None

set(key, value, time=None)¶: Always return True

class rc.FakeRedisCache(namespace=None, serializer_cls=None, default_expire=259200)¶

Uses a fake redis server as backend. It depends on the fakeredis library.

Parameters:	namespace – a prefix that should be added to all keys. serializer_cls – the serialization class you want to use. By default, it is `rc.JSONSerializer`. default_expire – default expiration time that is used if no expire specified on `set()`.

Cluster Host Config¶

class rc.redis_cluster.HostConfig(host_name, host='localhost', port=6379, unix_socket_path=None, db=0, password=None, ssl=False, ssl_options=None)¶

Promise Object¶

class rc.promise.Promise¶

A promise object. You can access promise.value to get the resolved value. Here is one example:

p = Promise()
assert p.is_pending
assert not p.is_resolved
assert p.value is None
p.resolve('value')
assert not p.is_pending
assert p.is_resolved
assert p.value == 'value'

is_pending¶: Return True if the promise is pending.

is_resolved¶: Return True if the promise is resolved.

resolve(value)¶: Resolves with value.

then(on_resolve=None)¶

Add one callback that is called with the resolved value when the promise is resolved, and return the promise itself. One demo:

p = Promise()
d = {}
p.then(lambda v: d.setdefault('key', v))
p.resolve('value')
assert p.value == 'value'
assert d['key'] == 'value'

API¶

Base Cache System API¶

Cache Object¶

Cache Cluster Object¶

Serializer¶

Redis Router¶

Testing Objects¶

Cluster Host Config¶

Promise Object¶

Table Of Contents

Related Topics

This Page