CacheManagerMixin¶

class privex.helpers.cache.extras.CacheManagerMixin[source]¶

CacheManagerMixin is a class mixin which adds various methods and settings to assist with class-scoped caching, including an adjustable class-level cache prefix cache_prefix, a method to remove all known cache keys managed by your class clear_all_cache_keys(), and a special decorator which automatically integrates with your class z_cache() by intercepting the first argument of a method call.

After you’ve extended CacheManagerMixin, you can enable argument-based caching for any method, simply by adding the decorator line @z_cache() above it. z_cache() will automatically handle the cache key name, including extracting your method’s passed arguments and inserting them into the cache key, ensuring method calls with certain arguments, are cached separately from other method calls with a different set of arguments.

Most methods of this class are generally only used internally, or for certain niche use cases, but there are some methods that can be useful in almost any use case:

get_all_cache_keys() - returns a set of all known cache keys used by your class. Note that this method relies on the “cache key log”, which will only be aware of keys that were cached within the last default_cache_key_time seconds.

clear_cach_keys() - manually remove individual cache keys immediately

clear_all_cache_keys() - as the name implies, this method will remove all known cache keys that are found inside of the cache key log ( cache_key_log_name )

cache_set() - set a cache key directly from the body of a method. The key that you enter, will be automatically prefixed with the appropriate cache_prefix, so you don’t need to worry about manually prefixing your cache key names.

cache_get() - retrieve the contents of a given cache key name - if it exists. Just like with cache_set(), this method will automatically prefix the key you enter. Additionally, by default, if the key you’re trying to retrieve doesn’t exist, it will make a second cache call without the prefix, in-case that you were really wanting the literal key you entered (not the auto-prefixed key). The automatic no-prefix-fallback can be disabled, see the docs for that method.

cache_get_or_set() - a combination of get() and set() - if the key you’re trying to retrieve doesn’t exist, then the fallback value will be set on that cache key and returned. Additionally, you may specify a “callback” for value, i.e. a function/method which will be called if key doesn’t exist, which should return the new value which should be set on the key and returned.

Example:

>>> from privex.helpers.cache.extras import CacheManagerMixin, z_cache
>>> from time import sleep
>>>
>>> class MyClass(CacheManagerMixin):
...     # It's recommended, but not necessary - to re-create cache_key_lock with None, as it will ensure your
...     # class has a separate threading.Lock() instance from other CacheManagerMixin based classes
...     cache_key_lock: Optional[threading.Lock] = None
...     # You should override cache_prefix to ensure cache keys auto-created for your class won't
...     # conflict with cache keys created by other classes
...     cache_prefix: str = 'my_class'
...     # While it's possible to set the cache timeout per method with z_cache / per call to cache_set,
...     # it's helpful to adjust default_cache_time to a number of seconds which is suitable for most
...     # methods in your class, avoiding the need to specify it each time..
...     default_cache_time: Union[float, int] = 300
...     # default_cache_key_time should generally be set to the same number of seconds as default_cache_time.
...     # It controls how long the "cache key log" is held for, which is simply a list of known cache keys for
...     # your class, enabling the use of the method .clear_all_cache_keys
...     default_cache_key_time: Union[float, int] = 300
...
...     @z_cache()
...     def hello(self, world=10):
...         sleep(5)
...         return f"Hello world: {world}"
...
>>> c = MyClass()
>>> # The first call to hello() will take 5 seconds due to the sleep
>>> c.hello()
Hello world: 10
>>> c.hello()   # But when we call it again - it returns instantly
Hello world: 10
>>> # If we call .hello() with a different set of arguments, it will result in a new cache key being auto-generated,
>>> # requiring a new, non-cached call to hello() to get the result for '5'
>>> c.hello(5)
Hello world: 5

__init__(): Initialize self. See help(type(self)) for accurate signature.

classmethod cache_get(key: str, default: Any = None, fail: bool = False, auto_prefix=True, fallback_prefix: bool = True)[source]¶

This is a simple helper method which calls cached.get() - while automatically prepending cache_prefix and cache_sep before the key.

Parameters

key (str) – The cache key (as a string) to get the value for, e.g. example:test
default (Any) – If the cache key key isn’t found / is expired, return this value (Default: None)
fail (bool) – If set to True, will raise CacheNotFound instead of returning default when a key is non-existent / expired.
auto_prefix (bool) – If set to True, will auto-prepend cache_prefix to key if it’s not present.
fallback_prefix (bool) – If set to True, if we fail to find key with the prefix prepended, then we’ll retry a cache lookup WITHOUT the key prefix.

Raises

CacheNotFound – Raised when fail=True and key was not found in cache / expired.

Return Any value

The value of the cache key key, or default if it wasn’t found.

classmethod cache_get_or_set(key: str, value: Any, timeout: Optional[Union[decimal.Decimal, int, float, str]] = <class 'privex.helpers.types.AutoDetected'>, auto_prefix=True)[source]¶

This is a simple helper method which calls cached.get_or_set() - while automatically prepending cache_prefix and cache_sep before the key.

Parameters

key (str) – The cache key (as a string) to get the value for, e.g. example:test
value (Any) – The value to store in the cache key key
timeout (int) – The amount of seconds to keep the data in cache. Pass None to disable expiration.
auto_prefix (bool) – If set to True, will auto-prepend cache_prefix to key if it’s not present.

Raises

CacheNotFound – Raised when fail=True and key was not found in cache / expired.

Return Any value

The value of the cache key key, or default if it wasn’t found.

cache_key_lock: Optional[_thread.allocate_lock] = None¶: A threading.Lock lock object which is used when adding cache keys to cache_key_log_name to prevent the risk of two simultaneous cache key additions causing one call to overwrite the other’s addition attempt.

cache_key_log_name: str = 'all_cache_keys'¶: The cache key name component for the key used to store a list of all known cache keys for your class

cache_prefix: str = 'pvx_cmgr'¶: The prefix used for all cache keys generated for your class

cache_sep: str = ':'¶: Separator character(s) used between identifying components within a cache key

classmethod cache_set(key: str, value: Any, timeout: Optional[Union[decimal.Decimal, int, float, str]] = <class 'privex.helpers.types.AutoDetected'>, auto_prefix: bool = True)[source]¶

This is a simple helper method which calls cached.set() - while automatically prepending cache_prefix and cache_sep before the key, plus when timeout=AUTO ( AUTO ), the timeout will be automatically set to the default timeout: default_cache_time

Parameters

key (str) – NOTE: Key will be auto-prepended with cache_prefixx - The cache key (as a string) to set the value for, e.g. ``example:test`
value (Any) – The value to store in the cache key key
timeout (int) – The amount of seconds to keep the data in cache. Pass None to disable expiration.
auto_prefix (bool) – If set to True, will auto-prepend cache_prefix to key if it’s not present.

Returns

classmethod clear_all_cache_keys()[source]¶

Remove all known cache keys related to this class which aren’t expired.

Uses the cache key log under the class specific key name cache_key_log_name, which is a cached list that contains all known cache keys that have been created by this class, whether via cache_set(), or using the CacheManager decorator z_cache()

default_cache_key_time: Union[float, int] = 300¶: Default number of seconds to cache the log of known cache keys

default_cache_time: Union[float, int] = 300¶: Default number of seconds to cache any objects

classmethod get_all_cache_keys() → Set[str][source]¶: Retrieve the list of cache keys as a set from the cache key 'query_cache_keys' which stores the list of query_hidden:xxx:xxx:xxx keys, allowing for easy clearing of those cache keys when needed. :return:

classmethod key_add_prefix(key: Union[str, Callable[[Any], str]], auto_prefix: bool = True, _auto_cache=True, call_args: list = None, call_kwargs: dict = None, _lock: Optional[Union[_thread.allocate_lock, Type[privex.helpers.cache.extras.NoLock]]] = None) → str ¶

Add this class’s cache key prefix to key if it isn’t already prefixed

Parameters

key (str|callable) – The key to prepend the cache key prefix onto - if not already prefixed. This may optionally be a function (e.g. a lambda) which returns a cache key to be auto-prefixed, and any necessary positional/keyword arguments for the function may be specified using the arguments call_args and call_kwargs
auto_prefix (bool) – This argument is mainly used by internal methods to reduce the need to copy/paste handling code which allows users to request that a method does not attempt to auto-prefix the key they entered.
_auto_cache (bool) – This is a boolean key, which controls whether or not keys are automatically logged to the cache key log, which is a list of all known cache keys for a given class. Uses log_cache_key()
call_args (list) – If key is a callable (e.g. a lambda), call_args can be set to a list of positional arguments to pass to the callable function key
call_kwargs (dict) – If key is a callable (e.g. a lambda), call_kwargs can be set to a dict of keyword arguments to pass to the callable function key
_lock (ANY_LCK) – This method itself does not use a lock, but it calls upon log_cache_key() which does use a lock. You may optionally pass a Lock instance if needed, e.g. to prevent a conflict where the calling function/method has already acquired the class-level lock. It can also be set to the dummy type NO_LOCK NO_LOCK to prevent using a lock.

Return str new_key

The original key after it may or may not have had a prefix prepended to it.

classmethod key_remove_prefix(key: str, prefix: str = None, sep: str = None)¶: Remove the cache key prefix from a given cache key

classmethod log_cache_key(key: str, _lock: Optional[Union[_thread.allocate_lock, Type[privex.helpers.cache.extras.NoLock]]] = None) → Set[str][source]¶

Add a cache key name to the cache key log cache_key_log_name. This usually doesn’t need to be called from outside of this class, since most methods which may add or edit a cache key should also insert/update the key into the cache key log.

Parameters

key (str) – The key to add to the cache key log.
_lock (ANY_LCK) – You may optionally pass a Lock instance if needed, e.g. to prevent a conflict where the calling function/method has already acquired the class-level lock cache_key_lock It can also be set to the dummy type NO_LOCK NO_LOCK to prevent using a lock.

Return Set[str] cache_key_log

The cache key log after adding ckeys

classmethod log_delete_cache_key(*ckeys: str, _lock: Optional[Union[_thread.allocate_lock, Type[privex.helpers.cache.extras.NoLock]]] = None) → Set[str]¶

Remove one or more cache key names from the cache key log cache_key_log_name. This usually doesn’t need to be called from outside of this class, since clear_cache_keys() automatically removes any logged cache key names after deleting the cache key itself from the global cache.

Parameters

ckeys (str) – One or more cache keys to remove from the cache key log
_lock (ANY_LCK) – You may optionally pass a Lock instance if needed, e.g. to prevent a conflict where the calling function/method has already acquired the class-level lock cache_key_lock It can also be set to the dummy type NO_LOCK NO_LOCK to prevent using a lock.

Return Set[str] cache_key_log

The cache key log after removing ckeys

classmethod log_delete_cache_keys(*ckeys: str, _lock: Optional[Union[_thread.allocate_lock, Type[privex.helpers.cache.extras.NoLock]]] = None) → Set[str][source]¶

Remove one or more cache key names from the cache key log cache_key_log_name. This usually doesn’t need to be called from outside of this class, since clear_cache_keys() automatically removes any logged cache key names after deleting the cache key itself from the global cache.

Parameters

ckeys (str) – One or more cache keys to remove from the cache key log
_lock (ANY_LCK) – You may optionally pass a Lock instance if needed, e.g. to prevent a conflict where the calling function/method has already acquired the class-level lock cache_key_lock It can also be set to the dummy type NO_LOCK NO_LOCK to prevent using a lock.

Return Set[str] cache_key_log

The cache key log after removing ckeys

Methods¶

Methods

`cache_get`(key[, default, fail, auto_prefix, …])	This is a simple helper method which calls `cached.get()` - while automatically prepending `cache_prefix` and `cache_sep` before the key.
`cache_get_or_set`(key, value[, timeout, …])	This is a simple helper method which calls `cached.get_or_set()` - while automatically prepending `cache_prefix` and `cache_sep` before the key.
`cache_set`(key, value[, timeout, auto_prefix])	This is a simple helper method which calls `cached.set()` - while automatically prepending `cache_prefix` and `cache_sep` before the key, plus when `timeout=AUTO` ( `AUTO` ), the timeout will be automatically set to the default timeout: `default_cache_time`
`clear_all_cache_keys`()	Remove all known cache keys related to this class which aren’t expired.
`clear_cache_keys`(*keys[, auto_prefix, …])
`gen_cache_key`(*args[, _auto_cache, …])
`get_all_cache_keys`()	Retrieve the list of cache keys as a `set` from the cache key `'query_cache_keys'` which stores the list of `query_hidden:xxx:xxx:xxx` keys, allowing for easy clearing of those cache keys when needed.
`key_add_prefix`(key[, auto_prefix, …])	Add this class’s cache key prefix to `key` if it isn’t already prefixed
`key_remove_prefix`(key[, prefix, sep])	Remove the cache key prefix from a given cache key
`log_cache_key`(key[, _lock])	Add a cache key name to the cache key log `cache_key_log_name`.
`log_delete_cache_key`(*ckeys[, _lock])	Remove one or more cache key names from the cache key log `cache_key_log_name`.
`log_delete_cache_keys`(*ckeys[, _lock])	Remove one or more cache key names from the cache key log `cache_key_log_name`.

Attributes¶

Attributes

`cache_key_lock`	A `threading.Lock` lock object which is used when adding cache keys to `cache_key_log_name` to prevent the risk of two simultaneous cache key additions causing one call to overwrite the other’s addition attempt.
`cache_key_log_name`	The cache key name component for the key used to store a list of all known cache keys for your class
`cache_prefix`	The prefix used for all cache keys generated for your class
`cache_sep`	Separator character(s) used between identifying components within a cache key
`default_cache_key_time`	Default number of seconds to cache the log of known cache keys
`default_cache_time`	Default number of seconds to cache any objects