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
orring.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
whenNone
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 intobytes
using the given encoding. - key_refactor (Optional[Callable[[str],str]]) – Roughly,
key = key_refactor(key)
will be run when key_refactor is notNone
; 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
allowsNone
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 arering.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()
andring.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 ofring.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 alwaystuple
. 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 alwaysdict
. When there is a variable-length positional argument, pass the values them as atuple
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.