ring.func.base — The building blocks of ring.func.*.

ring.func.base.factory(storage_backend, key_prefix, expire_default, coder, miss_value, user_interface, storage_class, default_action=Ellipsis, coder_registry=Ellipsis, on_manufactured=None, wire_slots=Ellipsis, ignorable_keys=None, key_encoding=None, key_refactor=None)

Create a decorator which turns a function into ring wire or wire bridge.

This is the base factory function that every internal Ring factories are based on. See the source code of ring.func.sync or ring.func.asyncio for actual usages and sample code.

Parameters:

• storage_backend (Any) – Actual storage backend instance.
• key_prefix (Optional[str]) – Specify storage key prefix when a str value is given; Otherwise a key prefix is automatically suggested based on the function signature. Note that the suggested key prefix is not compatible between Python 2 and 3.
• expire_default (Optional[float]) – Set the duration of seconds to expire the data when a number is given; Otherwise the default behavior depends on the backend. Note that the storage may or may not support expiration or persistent saving.
• coder (Union[str,ring.coder.Coder]) – A registered coder name or a coder object. See ring.coder — Auto encode/decode layer for details.
• miss_value (Any) – The default value when storage misses a given key.
• user_interface (type) – Injective implementation of sub-functions.
• storage_class (type) – Injective implementation of storage.
• default_action (Optional[str]) – The default action name for __call__ of the wire object. When the given value is None, there is no __call__ method for ring wire.
• coder_registry (Optional[ring.coder.Registry]) – The coder registry to load the given coder. The default value is ring.coder.registry when None is given.
• on_manufactured (Optional[Callable[[type(Wire),type(Ring)],None]]) – The callback function when a new ring wire or wire bridge is created.
• ignorable_keys (List[str]) – (experimental) Parameter names not to use to create storage key.
• key_encoding (Optional[str]) – The storage key is usually str typed. When this parameter is given, a key is encoded into bytes using the given encoding.
• key_refactor (Optional[Callable[[str],str]]) – Roughly, key = key_refactor(key) will be run when key_refactor is not None; Otherwise it is omitted.

Returns:

The factory decorator to create new ring wire or wire bridge.

Return type:

(Callable)->ring.wire.RopeCore

exception ring.func.base.NotFound

Internal exception for a cache miss.

Ring internally use this exception to indicate a cache miss. Though common convention of the cache miss is None for many implementations, ring.coder allows None to be proper cached value in Ring.

class ring.func.base.BaseUserInterface(ring)

The base user interface class for single item access.

An instance of interface class is bound to a Ring object. They have the one-to-one relationship. Subclass this class to create a new user interface. This is an abstract class. The methods marked as abc.abstractmethod() are mandatory; Otherwise not.

This class provides sub-functions of ring wires. When trying to access any sub-function of a ring wire which doesn’t exist, it looks up the composed user interface object and creates actual sub-function into the ring wire.

The parameter transform_args in ring.func.base.interface_attrs() defines the figure of method parameters. For the BaseUserInterface, some methods’ transform_args are ring.func.base.transform_args_prefix() which removes specified count of prefix. Other mix-ins or subclasses may have different transform_args.

The first parameter of interface method always is a RingWire object. The other parameters are composed by transform_args.

See:ring.func.base.transform_args_prefix() for the specific argument transformation rule for each methods.

The parameters below describe common methods’ parameters.

Parameters:

• wire (ring.func.base.RingWire) – The corresponding ring wire object.
• pargs (ArgPack) – Refined arguments pack.

delete(wire, pargs)

Delete the storage value of the corresponding key.

See:ring.func.base.BaseUserInterface.key() for the key. See:The class documentation for the parameter details. Return type:None

execute(wire, pargs)

Execute and return the result of the original function.

See:The class documentation for the parameter details. Returns:The result of the original function.

get(wire, pargs)

Try to get and return the storage value of the corresponding key.

See:The class documentation for the parameter details. See:ring.func.base.BaseUserInterface.key() for the key. Returns:The storage value for the corresponding key if it exists; Otherwise, the miss_value of Ring object.

get_or_update(wire, pargs)

Try to get and return the storage value; Otherwise, update and so.

See:ring.func.base.BaseUserInterface.get() for get. See:ring.func.base.BaseUserInterface.update() for update. See:The class documentation for the parameter details. Returns:The storage value for the corresponding key if it exists; Otherwise result of the original function.

has(wire, pargs)

Return whether the storage has a value of the corresponding key.

This is an optional function.

See:ring.func.base.BaseUserInterface.key() for the key. See:The class documentation for the parameter details. Returns:Whether the storage has a value of the corresponding key. Return type:bool

key(wire, pargs)

Create and return the composed key for storage.

See:The class documentation for the parameter details. Returns:The composed key with given arguments. Return type:str

set(wire, value, pargs)

Set the storage value of the corresponding key as the given value.

See:ring.func.base.BaseUserInterface.key() for the key. See:The class documentation for common parameter details. Parameters:value (Any) – The value to save in the storage. Return type:None

touch(wire, pargs)

Touch the storage value of the corresponding key.

This is an optional function.

Note:Touch means resetting the expiration. See:ring.func.base.BaseUserInterface.key() for the key. See:The class documentation for the parameter details. Return type:bool

update(wire, pargs)

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

This action is comprehensible as a concatenation of ring.func.base.BaseUserInterface.execute() and ring.func.base.BaseUserInterface.set().

See:ring.func.base.BaseUserInterface.key() for the key. See:ring.func.base.BaseUserInterface.execute() for the execution. See:The class documentation for the parameter details. Returns:The result of the original function.

class ring.func.base.BaseStorage(ring, backend)

Base storage interface.

To add a new storage interface, regard to use ring.func.base.CommonMixinStorage and a subclass of ring.func.base.StorageMixin.

When subclassing this interface, remember get and set methods must include coder works. The methods marked as abc.abstractmethod() are mandatory; Otherwise not.

backend

delete(key)

Delete data by given key.

get(key)

Get actual data by given key.

has(key)

Check data exists for given key.

rope

set(key, value, expire=Ellipsis)

Set actual data by given key, value and expire.

touch(key, expire=Ellipsis)

Touch data by given key.

class ring.func.base.CommonMixinStorage(ring, backend)

General storage root for StorageMixin.

delete(key)

Delete data by given key.

get(key)

Get actual data by given key.

has(key)

Check data exists for given key.

set(key, value, expire=Ellipsis)

Set actual data by given key, value and expire.

touch(key, expire=Ellipsis)

Touch data by given key.

class ring.func.base.StorageMixin

Abstract storage mixin class.

Subclass this class to create a new storage mixin. The methods marked as abc.abstractmethod() are mandatory; Otherwise not.

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)

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.base.AbstractBulkUserInterfaceMixin

Bulk access interface mixin.

Every method in this mixin is optional. The methods have each corresponding function in ring.func.base.BaseUserInterface.

The parameters below describe common methods’ parameters.

Parameters:

• wire (ring.func.base.RingWire) – The corresponding ring wire object.
• args_list (Iterable[Union[tuple,dict]]) – A sequence of arguments of the original function. While args_list is a list of args, each args (Union[tuple,dict]) is a complete set of positional-only formed or keyword-only formed arguments. When the args (tuple) is positional-only formed, its type must be always tuple. Any other iterable types like list are not allowed. When any keyword-only argument is required, use keyword-only formed arguments. When the args (dict) is keyword-only formed, its type must be always dict. When there is a variable-length positional argument, pass the values them as a tuple of parameters with the corresponding variable-length positional parameter name. The restriction gives the simple and consistent interface for multiple dispatching. Note that it only describes the methods which don’t have transform_args attribute.