memoize package

Submodules

memoize.coerced module

[Internal use only] Some functions work differently way depending if asyncio or Tornado is used - this is resolved here.

memoize.configuration module

[API] Provides interface (and built-in implementations) of full cache configuration.

class memoize.configuration.CacheConfiguration

Bases: object

Provides configuration for cache.

configured() → bool

Cache will raise NotConfiguredCacheCalledException if this returns false. May be useful if when cache is reconfigured in runtime.

entry_builder() → memoize.entrybuilder.CacheEntryBuilder

Determines which CacheEntryBuilder is to be used by cache.

eviction_strategy() → memoize.eviction.EvictionStrategy

Determines which EvictionStrategy is to be used by cache.

key_extractor() → memoize.key.KeyExtractor

Determines which KeyExtractor is to be used by cache.

method_timeout() → datetime.timedelta

Defines how much time wrapped method can take to complete.

storage() → memoize.storage.CacheStorage

Determines which CacheStorage is to be used by cache.

class memoize.configuration.DefaultInMemoryCacheConfiguration(capacity: int = 4096, method_timeout: datetime.timedelta = datetime.timedelta(seconds=120), update_after: datetime.timedelta = datetime.timedelta(seconds=600), expire_after: datetime.timedelta = datetime.timedelta(seconds=1800))

Bases: memoize.configuration.CacheConfiguration

Default parameters that describe in-memory cache. Be ware that parameters used do not suit every case.

configured() → bool

Cache will raise NotConfiguredCacheCalledException if this returns false. May be useful if when cache is reconfigured in runtime.

entry_builder() → memoize.entrybuilder.ProvidedLifeSpanCacheEntryBuilder

Determines which CacheEntryBuilder is to be used by cache.

eviction_strategy() → memoize.eviction.LeastRecentlyUpdatedEvictionStrategy

Determines which EvictionStrategy is to be used by cache.

key_extractor() → memoize.key.EncodedMethodReferenceAndArgsKeyExtractor

Determines which KeyExtractor is to be used by cache.

method_timeout() → datetime.timedelta

Defines how much time wrapped method can take to complete.

storage() → memoize.storage.LocalInMemoryCacheStorage

Determines which CacheStorage is to be used by cache.

class memoize.configuration.MutableCacheConfiguration(configured: bool, storage: memoize.storage.CacheStorage, key_extractor: memoize.key.KeyExtractor, eviction_strategy: memoize.eviction.EvictionStrategy, entry_builder: memoize.entrybuilder.CacheEntryBuilder, method_timeout: datetime.timedelta)

Bases: memoize.configuration.CacheConfiguration

Mutable configuration which can be change at runtime. May be also used to customize existing configuration (for example a default one, which is immutable).

configured() → bool

Cache will raise NotConfiguredCacheCalledException if this returns false. May be useful if when cache is reconfigured in runtime.

entry_builder() → memoize.entrybuilder.CacheEntryBuilder

Determines which CacheEntryBuilder is to be used by cache.

eviction_strategy() → memoize.eviction.EvictionStrategy

Determines which EvictionStrategy is to be used by cache.

static initialized_with(configuration: memoize.configuration.CacheConfiguration) → memoize.configuration.MutableCacheConfiguration

key_extractor() → memoize.key.KeyExtractor

Determines which KeyExtractor is to be used by cache.

method_timeout() → datetime.timedelta

Defines how much time wrapped method can take to complete.

set_configured(value: bool) → memoize.configuration.MutableCacheConfiguration

set_entry_builder(value: memoize.entrybuilder.CacheEntryBuilder) → memoize.configuration.MutableCacheConfiguration

set_eviction_strategy(value: memoize.eviction.EvictionStrategy) → memoize.configuration.MutableCacheConfiguration

set_key_extractor(value: memoize.key.KeyExtractor) → memoize.configuration.MutableCacheConfiguration

set_method_timeout(value: datetime.timedelta) → memoize.configuration.MutableCacheConfiguration

set_storage(value: memoize.storage.CacheStorage) → memoize.configuration.MutableCacheConfiguration

storage() → memoize.storage.CacheStorage

Determines which CacheStorage is to be used by cache.

exception memoize.configuration.NotConfiguredCacheCalledException

Bases: Exception

memoize.entry module

[Internal use only] Contains implementation of cache entry.

class memoize.entry.CacheEntry(created: datetime.datetime, update_after: datetime.datetime, expires_after: datetime.datetime, value: Any)

Bases: object

Implementation of cache entry used internally

memoize.entrybuilder module

[API] Provides interface (and built-in implementations) how cache entries should be constructed (responsibility of expiry & update after times lies here). This interface is used in cache configuration.

class memoize.entrybuilder.CacheEntryBuilder

Bases: object

build(key: str, value: Any) → memoize.entry.CacheEntry

Constructs cache entry object (sets creation time, can transform value, governs update/expiration times).

class memoize.entrybuilder.ProvidedLifeSpanCacheEntryBuilder(update_after: datetime.timedelta = datetime.timedelta(seconds=600), expire_after: datetime.timedelta = datetime.timedelta(seconds=1800))

Bases: memoize.entrybuilder.CacheEntryBuilder

CacheEntryBuilder which uses constant delays independent form values that are cached

build(key: str, value: Any) → memoize.entry.CacheEntry

Constructs cache entry object (sets creation time, can transform value, governs update/expiration times).

update_timeouts(update_after: datetime.timedelta, expire_after: datetime.timedelta) → None

memoize.eviction module

[API] Provides interface (and built-in implementations) how cache entries should be constructed (responsibility of expiry & update after times lies here). This interface is used in cache configuration.

class memoize.eviction.EvictionStrategy

Bases: object

mark_read(key: str) → None

Informs strategy that entry related to given key was read by current client.

mark_released(key: str) → None

Informs strategy that entry related to given key was deemed non-essential by current client.

mark_written(key: str, entry: memoize.entry.CacheEntry) → None

Informs strategy that entry related to given key was updated by current client.

next_to_release() → Optional[str]

Returns element that should be released by the current client according to this strategy (or None).

class memoize.eviction.LeastRecentlyUpdatedEvictionStrategy(capacity=4096)

Bases: memoize.eviction.EvictionStrategy

mark_read(key: str) → None

Informs strategy that entry related to given key was read by current client.

mark_released(key: str) → None

Informs strategy that entry related to given key was deemed non-essential by current client.

mark_written(key: str, entry: memoize.entry.CacheEntry) → None

Informs strategy that entry related to given key was updated by current client.

next_to_release() → Optional[str]

Returns element that should be released by the current client according to this strategy (or None).

class memoize.eviction.NoEvictionStrategy

Bases: memoize.eviction.EvictionStrategy

Strategy to be used when delegating eviction to cache itself. This strategy performs no actions.

mark_read(key: str) → None

Informs strategy that entry related to given key was read by current client.

mark_released(key: str) → None

Informs strategy that entry related to given key was deemed non-essential by current client.

mark_written(key: str, entry: memoize.entry.CacheEntry) → None

Informs strategy that entry related to given key was updated by current client.

next_to_release() → Optional[str]

Returns element that should be released by the current client according to this strategy (or None).

memoize.exceptions module

[API] Contains exceptions that may be exposed to the library client.

exception memoize.exceptions.CachedMethodFailedException

Bases: Exception

memoize.key module

[API] Provides interface (and built-in implementations) how cache keys are constructed. This interface is used in cache configuration.

class memoize.key.EncodedMethodNameAndArgsKeyExtractor(skip_first_arg_as_self=False)

Bases: memoize.key.KeyExtractor

Encodes method name, args & kwargs to string and uses that as cache entry key. This KeyExtractor is class-centric and creates same keys for all objects of the same type.

Note: If wrapped function is a method (has ‘self’ as first positional arg) you may want to exclude ‘self’ from key by setting ‘skip_first_arg_as_self’ flag. For static methods of ordinary functions flag should be set to ‘False’.

Warning: uses method name only, so be cautious and do not wrap methods of different classes with the same names while using same store and ‘skip_first_arg_as_self’ set to False.

format_key(method_reference, call_args: Tuple[Any, ...], call_kwargs: Dict[str, Any]) → str

Using wrapped method object, call args and call keyword args, prepare cache entry key.

class memoize.key.EncodedMethodReferenceAndArgsKeyExtractor

Bases: memoize.key.KeyExtractor

Encodes method reference, args & kwargs to string and uses that as cache entry key. This KeyExtractor is object-centric and creates different keys for different objects of the same type (so when you create new objects - for instance after app restart - old entries in external store like Redis will be unreachable).

format_key(method_reference, call_args: Tuple[Any, ...], call_kwargs: Dict[str, Any]) → str

Using wrapped method object, call args and call keyword args, prepare cache entry key.

class memoize.key.KeyExtractor

Bases: object

Provides logic of cache key construction.

format_key(method_reference, call_args: Tuple[Any, ...], call_kwargs: Dict[str, Any]) → str

Using wrapped method object, call args and call keyword args, prepare cache entry key.

memoize.memoize_configuration module

[API] Provides global config of the library. Translates environment variables into values used internally by the library.

memoize.serde module

[API] Provides interface (and built-in implementations) of SerDe that may be used to implement cache storage.

class memoize.serde.EncodingSerDe(serde: memoize.serde.SerDe, binary_encoding: str = 'zip')

Bases: memoize.serde.SerDe

Applies extra encoding to the data (for instance compression when ‘zip’ or ‘bz2’ codec used).

deserialize(value: bytes) → memoize.entry.CacheEntry

serialize(value: memoize.entry.CacheEntry) → bytes

class memoize.serde.JsonSerDe(string_encoding: str = 'utf-8', value_to_reversible_repr: Callable[[Any], Any] = <function JsonSerDe.<lambda>>, reversible_repr_to_value: Callable[[Any], Any] = <function JsonSerDe.<lambda>>)

Bases: memoize.serde.SerDe

Uses encoded json string as binary representation. Value of cached type should consist of types which are json-reversible (json.loads(json.dumps(v)) is equal to v) or one should provide (by constructor) functions converting values to/from such representation.

deserialize(data: bytes) → memoize.entry.CacheEntry

serialize(entry: memoize.entry.CacheEntry) → bytes

class memoize.serde.PickleSerDe(pickle_protocol=4)

Bases: memoize.serde.SerDe

Uses encoded pickles as binary representation.

deserialize(data: bytes) → memoize.entry.CacheEntry

serialize(entry: memoize.entry.CacheEntry) → bytes

class memoize.serde.SerDe

Bases: object

Responsible for (de)serialization of values handled by CacheStorage (if SerDes are supported).

deserialize(data: bytes) → memoize.entry.CacheEntry

serialize(entry: memoize.entry.CacheEntry) → bytes

memoize.statuses module

[Internal use only] Encapsulates update state management.

class memoize.statuses.UpdateStatuses(update_lock_timeout: datetime.timedelta = datetime.timedelta(seconds=300))

Bases: object

await_updated(key: str) → Awaitable[Optional[memoize.entry.CacheEntry]]

Waits (asynchronously) until update in progress has benn finished. Returns updated entry or None if update failed/timed-out. Should be called only if ‘is_being_updated’ returned True (and since then IO-loop has not been lost).

is_being_updated(key: str) → bool

Checks if update for given key is in progress. Obtained info is valid until control gets back to IO-loop.

mark_being_updated(key: str) → None

Informs that update has been started. Should be called only if ‘is_being_updated’ returned False (and since then IO-loop has not been lost).. Calls to ‘is_being_updated’ will return True until ‘mark_updated’ will be called.

mark_update_aborted(key: str) → None

Informs that update failed to complete. Calls to ‘is_being_updated’ will return False until ‘mark_being_updated’ will be called.

mark_updated(key: str, entry: memoize.entry.CacheEntry) → None

Informs that update has been finished. Calls to ‘is_being_updated’ will return False until ‘mark_being_updated’ will be called.

memoize.storage module

[API] Provides interface (and built-in implementations) of storage for cache entries. This interface is used in cache configuration.

class memoize.storage.CacheStorage

Bases: object

get(key: str) → Optional[memoize.entry.CacheEntry]

Request value for given key. If currently there is no such value, returns None. Has to be async.

offer(key: str, entry: memoize.entry.CacheEntry) → None

Offer entry to be stored. If storage already has more relevant data, offer may be declined. Has to be async.

release(key: str) → None

Declare that current client does not need entry determined by given key. Has to be async.

class memoize.storage.LocalInMemoryCacheStorage

Bases: memoize.storage.CacheStorage

Implementation that stores all entries as-is in a dictionary residing solely in memory.

get(key: str) → Optional[memoize.entry.CacheEntry]

Request value for given key. If currently there is no such value, returns None. Has to be async.

offer(key: str, entry: memoize.entry.CacheEntry) → None

Offer entry to be stored. If storage already has more relevant data, offer may be declined. Has to be async.

release(key: str) → None

Declare that current client does not need entry determined by given key. Has to be async.

memoize.wrapper module

[API] Provides an entry point to the library - a wrapper that is used to cache entries.

memoize.wrapper.memoize(method: Optional[Callable] = None, configuration: memoize.configuration.CacheConfiguration = None, invalidation: memoize.invalidation.InvalidationSupport = None)

Wraps function with memoization.

If entry reaches time it should be updated, refresh is performed in background, but current entry is still valid and may be returned. Once expiration time is reached, refresh is blocking and current entry is considered invalid.

Note: If wrapped method times out after method_timeout (see configuration) the cache will not be populated and a failure occurs.

Note: If wrapped method throws an exception the cache will not be populated and failure occurs.

Note: Failures are indicated by designated exceptions (not original ones).

To force refreshing immediately upon call to a cached method, set ‘force_refresh_memoized’ keyword flag, so the method will block until it’s cache is refreshed.

Warning: Leaving default configuration is a bad idea as it may not fit your data (may cause OOMs or cache for an inappropriate time).

Parameters:

• method (function) – function to be decorated
• configuration (CacheConfiguration) – cache configuration; default: DefaultInMemoryCacheConfiguration
• invalidation (InvalidationSupport) – pass created instance of InvalidationSupport to have it configured

Raises:

CachedMethodFailedException upon call: if cached method timed-out or thrown an exception

Raises:

NotConfiguredCacheCalledException upon call: if provided configuration is not ready

Module contents