Cache

enum q2_sdk.core.cache.CacheReturnCode(value)[source]

Bases: IntEnum

Member Type:: int

Valid values are as follows:

String = <CacheReturnCode.String: 1>

Json = <CacheReturnCode.Json: 2>

Integer = <CacheReturnCode.Integer: 3>

Encrypted = <CacheReturnCode.Encrypted: 4>

exception q2_sdk.core.cache.CacheConfigError[source]

Bases: Exception

Bad configs to instantiate Q2CacheClient

q2_sdk.core.cache.deserialize_json(value, flags, compress_data, encryption_key)[source]

Parameters:

value – Raw value to deserialize
flags (CacheReturnCode) – 1=str, 2=json, 3=int, 4=encrypted
compress_data (bool) – is_zlib compressed
encryption_key (Optional[bytes]) – If present, will decrypt with security module

class q2_sdk.core.cache.RecentKeysStack(max_size, seed_from_file=False)[source]

Bases: ForkedUniqueStack

Configure RecentKeys to work with forked mode

append(item)[source]: Append object to the end of the list.

remove_safe(item)[source]: Same as .remove but will not except if it doesn’t exist

class q2_sdk.core.cache.RecentKey(key, prefix='', is_encrypted=False, expire_time=None)[source]

Bases: object

RecentKey(key: ‘str’, prefix: ‘str’ = ‘’, is_encrypted: ‘bool’ = False, expire_time: ‘Optional[datetime]’ = None)

class q2_sdk.core.cache.Q2CacheClient(*args, logger=None, prefix=None, local_path=None, encryption_key=None, **kwargs)[source]

Bases: PooledClient

Same interface as pymemcache base class, but remembers the keys being requested, which makes it easy to bust the cache

Parent docs: https://pymemcache.readthedocs.io/en/latest/apidoc/pymemcache.client.base.html#module-pymemcache.client.base

get(key, default=None, **kwargs)[source]

Parameters:

key (str) – Will prepend CACHE[‘PREFIX’] from settings file
default – Returned if the key was not found

get_many(keys)[source]

Parameters:: keys (List[str]) – Will prepend CACHE[‘PREFIX’] from settings file to all

set(key, value, expire=0, noreply=None)[source]

Parameters:

key (str) – Will prepend CACHE[‘PREFIX’] from settings file
value (str | dict | int | list) – Automatically compressed
expire – In seconds. 0 for no expiry (the default)
noreply – If False, will wait for Memcached to respond. Typically you will want to leave this alone.

set_and_return(key, value, expire=0, noreply=None)[source]

Simple wrapper to set that returns the value and raises a MemcacheError if the result is not True

Parameters:

key (str) – Will prepend CACHE[‘PREFIX’] from settings file
value (str | dict | int | list) – Automatically compressed
expire – In seconds. 0 for no expiry (the default)
noreply – If False, will wait for Memcached to respond. Typically, you will want to leave this alone.

set_many(values, expire=0, noreply=None)[source]

A convenience function for setting multiple values.

Parameters:

values (Union[Dict[str, str], Dict[str, dict], Dict[str, int], Dict[str, list]]) – {key: value, key2: value2}
expire – In seconds. 0 for no expiry (the default)
noreply – If False, will wait for Memcached to respond. Typically you will want to leave this alone.

delete_many(keys, noreply=None)[source]

A convenience function to delete multiple keys.

Parameters:

key – Will prepend CACHE[‘PREFIX’] from settings file
noreply – If False, will wait for Memcached to respond. Typically you will want to leave this alone.

flush_all(delay=0, noreply=None)[source]

A convenience function to clear all cached keys.

Parameters:

delay – optional int, the number of seconds to wait before flushing, or zero to flush immediately (the default).
noreply – If False, will wait for Memcached to respond. Typically you will want to leave this alone.

async get_async(key, default=None, **kwargs)[source]

Same as get but will run in a separate thread

Parameters:

key (str) – Will prepend CACHE[‘PREFIX’] from settings file
default – Returned if the key was not found

async get_many_async(keys)[source]

Same as get_many but will run in a separate thread

Parameters:: keys (List[str]) – Will prepend CACHE[‘PREFIX’] from settings file to all

async set_async(key, value, expire=0, noreply=None)[source]

Same as set but will run in a separate thread

Parameters:

key (str) – Will prepend CACHE[‘PREFIX’] from settings file
value (str | dict | int | list) – Automatically compressed
expire – In seconds. 0 for no expiry (the default)
noreply – If False, will wait for Memcached to respond. Typically you will want to leave this alone.

async set_and_return_async(key, value, expire=0, noreply=None)[source]

Simple wrapper to set that returns the value and raises a MemcacheError if the result is not True

Parameters:

key (str) – Will prepend CACHE[‘PREFIX’] from settings file
value (str | dict | int | list | partial) – Automatically compressed
expire – In seconds. 0 for no expiry (the default)
noreply – If False, will wait for Memcached to respond. Typically, you will want to leave this alone.

async set_many_async(values, expire=0, noreply=None)[source]

Same as set_many but will run in a separate thread

Parameters:

values (Dict[str, str | dict | int | list]) – {key: value, key2: value2}
expire – In seconds. 0 for no expiry (the default)
noreply – If False, will wait for Memcached to respond. Typically you will want to leave this alone.

async delete_many_async(keys, noreply=None)[source]

Same as delete_many but will run in a separate thread

Parameters:

key – Will prepend CACHE[‘PREFIX’] from settings file
noreply – If False, will wait for Memcached to respond. Typically you will want to leave this alone.

async flush_all_async(delay=0, noreply=None)[source]

Same as flush_all but will run in a separate thread

Parameters:

delay – optional int, the number of seconds to wait before flushing, or zero to flush immediately (the default).
noreply – If False, will wait for Memcached to respond. Typically you will want to leave this alone.

enum q2_sdk.core.cache.LocalCacheAction(value)[source]

Bases: StrEnum

Member Type:: str

Valid values are as follows:

READ = <LocalCacheAction.READ: 'read'>

SET = <LocalCacheAction.SET: 'set'>

CLEAR = <LocalCacheAction.CLEAR: 'clear'>

UPDATE = <LocalCacheAction.UPDATE: 'update'>

q2_sdk.core.cache.get_cache(logger=None, prefix=None, cachemock_params=None, encryption_key=None, **kwargs)[source]

Parameters:

prefix – If defined will be prepended to all keys
logger – Reference to calling request’s logger (self.logger in your extension)

Return type:

Q2CacheClient

enum q2_sdk.core.cache.StorageLevel(value)[source]

Bases: StrEnum

At what scope should the cache be stored?

Parameters:

Service – Cache will be scoped to the service
Stack – Cache will be scoped to the customer stack (self.hq_credentials.customer_key)
Session – Cache will be scoped to the user session (self.online_session.session_id)

Member Type:

str

Valid values are as follows:

Service = <StorageLevel.Service: 'service'>

Stack = <StorageLevel.Stack: 'stack'>

Session = <StorageLevel.Session: 'session'>

q2_sdk.core.cache.cache_key(fn, *args, **kwargs)[source]: Simple function that returns a unique key based on function name, and arguments

q2_sdk.core.cache.cache(_func=None, *, timeout=300, key=<function cache_key>, key_prefix=None, storage_level=StorageLevel.Stack, **kw)[source]

Decorator to handle caching elegantly.

Usage: @cache(timeout=300, key=’cacheKey’, key_prefix=’keyPrefix’, storage_level=StorageLevel.Stack) def func(foo, bar): …

If the key is present, it returns the cached value instead of running the function. If the key is not yet cached, it executes the function and stores the value under the key.

By default, the cache key is the qualified name of the function for the active stack (customer environment). You can override the function name portion with the “key” parameter, and the stack portion with the “storage_level” parameter. The key is set using the “Q2CacheClient.set()” method, and you can add any additional prefix according to the client’s configs. You can also add a decorator-specific prefix using the “key_prefix” parameter.

The “timeout” parameter specifies the duration, in seconds, that the function is cached. It defaults to 300 seconds (5 minutes).

Parameters:

timeout (int) – Duration, in seconds, the function is cached. This argument defaults to 300 seconds (5 minutes)
key (Union[Callable, str, None]) – Optional cache key that may be set, the default is the qualified name of the function.
key_prefix (Optional[str]) – A string that will be automatically included (prepended by default) to all cache keys
storage_level (StorageLevel) – StorageLevel enum, Service: Scoped to this service, Stack: Scoped to the customer env,

Session: Scoped to the user session. If no level is passed the function’s self.default_storage_level will be used. Finally if that isn’t available the ‘Stack` level will be used.