ring.func.sync — collection of synchronous factory functions.

This module includes building blocks and storage implementations of Ring factories.

ring.func.sync.lru(lru=None, key_prefix=None, expire=None, coder=None, user_interface=<class 'ring.func.sync.CacheUserInterface'>, storage_class=<class 'ring.func.sync.LruStorage'>, maxsize=128, **kwargs)

LRU(Least-Recently-Used) cache interface.

Because the lru backend is following the basic manner of functools.lru_cache(), see also the document if you are not familiar with it.

>>> @ring.lru(maxsize=128)
>>> def f(...):
...     ...

The above is very similar to below:

>>> @functools.lru_cache(maxsize=128, typed=False)
>>> def f(...):
...     ...

Note that ring basically supports key consistency and manual operation features, unlike functools.lru_cache().

Parameters:
  • lru (ring.func.lru_cache.LruCache) – Cache storage. If the default value None is given, a new LruCache object will be created. (Recommended)
  • maxsize (int) – The maximum size of the cache storage.
See:

functools.lru_cache() for LRU cache basics.
See:

ring.func.sync.CacheUserInterface() for sub-functions.
ring.func.sync.dict(obj, key_prefix=None, expire=None, coder=None, user_interface=<class 'ring.func.sync.CacheUserInterface'>, storage_class=None, **kwargs)

Basic Python dict based cache.

This backend is not designed for real products. Please carefully read the next details to check it fits your demands.

  • ring.lru() and functools.lru_cache() are the standard way for the most of local cache.
  • Expired objects will never be removed from the dict. If the function has unlimited input combinations, never use dict.
  • It is designed to “simulate” cache backends, not to provide an actual cache backend. If a caching function is a fast job, this backend even can drop the performance.
Parameters:obj (dict) – Cache storage. Any dict compatible object.
See:ring.func.sync.CacheUserInterface() for sub-functions.
See:ring.dict() for asyncio version.
ring.func.sync.memcache(client, key_prefix=None, expire=0, coder=None, user_interface=(<class 'ring.func.sync.CacheUserInterface'>, <class 'ring.func.sync.BulkInterfaceMixin'>), storage_class=<class 'ring.func.sync.MemcacheStorage'>, **kwargs)

Common Memcached interface.

This backend is shared interface for various memcached client libraries below:

Most of them expect Memcached client or dev package is installed on your machine. If you are new to Memcached, check how to install it and the python package on your platform.

The expected types for input and output are always bytes for None coder, but you may use different types depending on client libraries. Ring doesn’t guarantee current/future behavior except for bytes.

Note:touch feature availability depends on Memcached library.
Parameters:
  • client (object) –

    Memcached client object. See below for details.

    • pymemcache: pymemcache.client.Client
    >>> client = pymemcache.client.Client(('127.0.0.1', 11211))
>>> @ring.memcache(client, ...)
...     ...
    • python-memcached or python3-memcached: memcache.Client
    >>> client = memcache.Client(["127.0.0.1:11211"])
>>> @ring.memcache(client, ...)
...     ...
    • pylibmc: pylibmc.Client
    >>> client = pylibmc.Client(['127.0.0.1'])
>>> @ring.memcache(client, ...)
...     ...
  • key_refactor (object) – The default key refactor may hash the cache key when it doesn’t meet Memcached key restriction.
See:

ring.func.sync.CacheUserInterface() for single access sub-functions.
See:

ring.func.sync.BulkInterfaceMixin() for bulk access sub-functions.
See:

ring.aiomcache() for asyncio version.
ring.func.sync.redis_py(client, key_prefix=None, expire=None, coder=None, user_interface=(<class 'ring.func.sync.CacheUserInterface'>, <class 'ring.func.sync.BulkInterfaceMixin'>), storage_class=<class 'ring.func.sync.RedisStorage'>, **kwargs)

Redis interface.

This backend depends on redis-py.

The redis package expects Redis client or dev package is installed on your machine. If you are new to Redis, check how to install Redis and the Python package on your platform.

Note that redis.StrictRedis is expected, which is different from redis.Redis.

Parameters:client (redis.StrictRedis) –

Redis client object. See redis.StrictRedis

>>> client = redis.StrictRedis()
>>> @ring.redis(client, ...)
...     ...
See:ring.func.sync.CacheUserInterface() for single access sub-functions.
See:ring.func.sync.BulkInterfaceMixin() for bulk access sub-functions.
See:ring.aioredis() for asyncio version.
See:Redis for Redis documentation.
ring.func.sync.redis_py_hash(client, hash_key=None, key_prefix=None, coder=None, user_interface=(<class 'ring.func.sync.CacheUserInterface'>, <class 'ring.func.sync.BulkInterfaceMixin'>), storage_class=<class 'ring.func.sync.RedisHashStorage'>, **kwargs)

This backend depends on redis-py.

This implements HASH commands in Redis.

Note that redis.StrictRedis is expected, which is different from redis.Redis.

Parameters:client (redis.StrictRedis) –

Redis client object. See redis.StrictRedis

>>> client = redis.StrictRedis()
>>> @ring.redis_hash(client, ...)
...     ...
See:ring.func.sync.CacheUserInterface() for single access sub-functions.
See:ring.func.sync.BulkInterfaceMixin() for bulk access sub-functions.
See:Redis for Redis documentation.
ring.func.sync.shelve(shelf, key_prefix=None, coder=None, user_interface=<class 'ring.func.sync.CacheUserInterface'>, storage_class=<class 'ring.func.sync.ShelveStorage'>, **kwargs)

Python shelve based cache.

Parameters:shelf (shelve.Shelf) –

A shelf storage. See shelve to create a shelf.

>>> shelf = shelve.open('shelve')
>>> @ring.shelve(shelf, ...)
...     ...
See:shelve for the backend.
See:ring.func.sync.CacheUserInterface() for sub-functions.
ring.func.sync.diskcache(obj, key_prefix=None, expire=None, coder=None, user_interface=<class 'ring.func.sync.CacheUserInterface'>, storage_class=<class 'ring.func.sync.DiskCacheStorage'>, **kwargs)

diskcache interface.

Parameters:obj (diskcache.Cache) –

diskcache Cache object. See diskcache.Cache.

>>> storage = diskcache.Cache('cachedir')
>>> @ring.disk(storage, ...)
...     ...
See:ring.func.sync.CacheUserInterface() for sub-functions.
class ring.func.sync.CacheUserInterface(ring)

General cache user interface provider.

See:ring.func.base.BaseUserInterface for class and methods details.
class ring.func.sync.BulkInterfaceMixin

Bulk access interface mixin.

Any corresponding storage class must be a subclass of ring.func.sync.BulkStorageMixin.

delete_many(wire, pargs)

Delete the storage values of the corresponding keys.

See:The class documentation for the parameter details.
Return type:None
execute_many(wire, pargs)

Execute and return the results of the original function.

See:The class documentation for the parameter details.
Returns:A sequence of the results of the original function.
Return type:Sequence of the return type of the original function
get_many(wire, pargs)

Try to get and returns the storage values.

See:The class documentation for the parameter details.
Returns:A sequence of the storage values or miss_value for the corresponding keys. When a key exists in the storage, the matching value is selected; Otherwise the miss_value of Ring object is.
get_or_update_many(wire, pargs)

Try to get and returns the storage values.

Note:The semantics of this function may vary by the implementation.
See:The class documentation for the parameter details.
Returns:A sequence of the storage values or the executed result of the original function for the corresponding keys. When a key exists in the storage, the matching value is selected; Otherwise, the result of the original function is.
has_many(wire, pargs)

Return whether the storage has values of the corresponding keys.

See:The class documentation for the parameter details.
Return type:Sequence[bool]
set_many(wire, pargs)

Set the storage values of the corresponding keys as the given values.

See:The class documentation for common parameter details.
Parameters:value_list (Iterable[Any]) – A list of the values to save in the storage.
Return type:None
touch_many(wire, pargs)

Touch the storage values of the corresponding keys.

See:The class documentation for the parameter details.
Return type:None
update_many(wire, pargs)

Execute the original function and set the result as the value.

See:The class documentation for the parameter details.
Returns:A sequence of the results of the original function.
Return type:Sequence of the return type of the original function
class ring.func.sync.BulkStorageMixin
delete_many(keys)
get_many(keys, miss_value)
has_many(keys)
set_many(keys, values, expire=Ellipsis)
touch_many(keys, expire=Ellipsis)
class ring.func.sync.LruStorage(ring, backend)
delete_value(key)

Delete value for the given key.

get_value(key)

Get and return value for the given key.

has_value(key)

Check and return data existences for the given key. (optional)

in_memory_storage = True
set_value(key, value, expire)

Set value for the given key, value and expire.

touch_value(key, expire)

Touch value for the given key. (optional)

class ring.func.sync.ExpirableDictStorage(ring, backend)
delete_value(key)

Delete value for the given key.

get_value(key)

Get and return value for the given key.

has_value(key)

Check and return data existences for the given key. (optional)

in_memory_storage = True
now()

time() -> floating point number

Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.

set_value(key, value, expire)

Set value for the given key, value and expire.

touch_value(key, expire)

Touch value for the given key. (optional)

class ring.func.sync.PersistentDictStorage(ring, backend)
delete_value(key)

Delete value for the given key.

get_value(key)

Get and return value for the given key.

has_value(key)

Check and return data existences for the given key. (optional)

in_memory_storage = True
set_value(key, value, expire)

Set value for the given key, value and expire.

class ring.func.sync.ShelveStorage(ring, backend)
delete_value(key)

Delete value for the given key.

set_value(key, value, expire)

Set value for the given key, value and expire.

class ring.func.sync.DiskCacheStorage(ring, backend)
delete_value(key)

Delete value for the given key.

get_value(key)

Get and return value for the given key.

set_value(key, value, expire)

Set value for the given key, value and expire.

class ring.func.sync.MemcacheStorage(ring, backend)
delete_many_values(keys)
delete_value(key)

Delete value for the given key.

get_many_values(keys)
get_value(key)

Get and return value for the given key.

set_many_values(keys, values, expire)
set_value(key, value, expire)

Set value for the given key, value and expire.

touch_value(key, expire)

Touch value for the given key. (optional)

class ring.func.sync.RedisStorage(ring, backend)
delete_value(key)

Delete value for the given key.

get_many_values(keys)
get_value(key)

Get and return value for the given key.

has_value(key)

Check and return data existences for the given key. (optional)

set_many_values(keys, values, expire)
set_value(key, value, expire)

Set value for the given key, value and expire.

touch_value(key, expire)

Touch value for the given key. (optional)

class ring.func.lru_cache.LruCache(maxsize)

Created by breaking down functools.lru_cache from CPython 3.7.0.

now()

time() -> floating point number

Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.