memoize package

Submodules

memoize.configuration module

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

class memoize.configuration.CacheConfiguration

Bases: object

Provides configuration for cache.

abstract configured() → bool

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

abstract entry_builder() → CacheEntryBuilder

Determines which CacheEntryBuilder is to be used by cache.

abstract eviction_strategy() → EvictionStrategy

Determines which EvictionStrategy is to be used by cache.

abstract key_extractor() → KeyExtractor

Determines which KeyExtractor is to be used by cache.

abstract method_timeout() → timedelta

Defines how much time wrapped method can take to complete.

abstract postprocessing() → Postprocessing

Determines which/if Postprocessing is to be used by cache.

abstract storage() → CacheStorage

Determines which CacheStorage is to be used by cache.

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

Bases: 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() → ProvidedLifeSpanCacheEntryBuilder

Determines which CacheEntryBuilder is to be used by cache.

eviction_strategy() → LeastRecentlyUpdatedEvictionStrategy

Determines which EvictionStrategy is to be used by cache.

key_extractor() → EncodedMethodReferenceAndArgsKeyExtractor

Determines which KeyExtractor is to be used by cache.

method_timeout() → timedelta

Defines how much time wrapped method can take to complete.

postprocessing() → Postprocessing

Determines which/if Postprocessing is to be used by cache.

storage() → LocalInMemoryCacheStorage

Determines which CacheStorage is to be used by cache.

class memoize.configuration.MutableCacheConfiguration(configured: bool, storage: CacheStorage, key_extractor: KeyExtractor, eviction_strategy: EvictionStrategy, entry_builder: CacheEntryBuilder, postprocessing: Postprocessing, method_timeout: timedelta)

Bases: 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() → CacheEntryBuilder

Determines which CacheEntryBuilder is to be used by cache.

eviction_strategy() → EvictionStrategy

Determines which EvictionStrategy is to be used by cache.

static initialized_with(configuration: CacheConfiguration) → MutableCacheConfiguration

key_extractor() → KeyExtractor

Determines which KeyExtractor is to be used by cache.

method_timeout() → timedelta

Defines how much time wrapped method can take to complete.

postprocessing() → Postprocessing

Determines which/if Postprocessing is to be used by cache.

set_configured(value: bool) → MutableCacheConfiguration

set_entry_builder(value: CacheEntryBuilder) → MutableCacheConfiguration

set_eviction_strategy(value: EvictionStrategy) → MutableCacheConfiguration

set_key_extractor(value: KeyExtractor) → MutableCacheConfiguration

set_method_timeout(value: timedelta) → MutableCacheConfiguration

set_postprocessing(value: Postprocessing) → MutableCacheConfiguration

set_storage(value: CacheStorage) → MutableCacheConfiguration

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, update_after: datetime, expires_after: 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

abstract build(key: str, value: Any) → CacheEntry

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

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

Bases: CacheEntryBuilder

CacheEntryBuilder which uses constant delays independent form values that are cached

build(key: str, value: Any) → CacheEntry

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

update_timeouts(update_after: timedelta, expire_after: 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

abstract mark_read(key: str) → None

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

abstract mark_released(key: str) → None

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

abstract mark_written(key: str, entry: CacheEntry) → None

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

abstract next_to_release() → str | None

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

class memoize.eviction.LeastRecentlyUpdatedEvictionStrategy(capacity=4096)

Bases: 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: CacheEntry) → None

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

next_to_release() → str | None

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

class memoize.eviction.NoEvictionStrategy

Bases: 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: CacheEntry) → None

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

next_to_release() → str | None

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.invalidation module

class memoize.invalidation.InvalidationSupport

Bases: object

Allows to manually invalidate cache entries.

async invalidate_for_arguments(call_args: Tuple[Any, ...], call_kwargs: Dict[str, Any]) → None

Provide agrs and kwargs for which you want to invalidate cache.

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: 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: 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.

abstract 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.postprocessing module

class memoize.postprocessing.DeepcopyPostprocessing

Bases: Postprocessing

apply(original: Any) → Any

Performs deep copy of the value. Useful when you want to prevent modifying the value cached in memory (so callers could modify their copies safely).

Have in mind that this operation may be expensive, and may not be suitable for all types of values (see docs on copy.deepcopy).

class memoize.postprocessing.NoPostprocessing

Bases: Postprocessing

apply(original: Any) → Any

Applies no postprocessing (returns original value).

class memoize.postprocessing.Postprocessing

Bases: object

abstract apply(original: Any) → Any

Transforms value just before returning from the cache.

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: SerDe, binary_encoding: str = 'zip')

Bases: SerDe

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

deserialize(value: bytes) → CacheEntry

serialize(value: CacheEntry) → bytes

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

Bases: 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) → CacheEntry

serialize(entry: CacheEntry) → bytes

class memoize.serde.PickleSerDe(pickle_protocol=5)

Bases: SerDe

Uses encoded pickles as binary representation.

deserialize(data: bytes) → CacheEntry

serialize(entry: CacheEntry) → bytes

class memoize.serde.SerDe

Bases: object

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

abstract deserialize(data: bytes) → CacheEntry

abstract serialize(entry: CacheEntry) → bytes

memoize.statuses module

[Internal use only] Encapsulates update state management.

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

Bases: object

await_updated(key: str) → Awaitable[CacheEntry | Exception]

Waits (asynchronously) until update in progress has benn finished. Returns awaitable with the updated entry (or awaitable with an exception 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, exception: Exception) → None

Informs that update failed to complete. Calls to ‘is_being_updated’ will return False until ‘mark_being_updated’ will be called. Accepts exception to propagate it across all clients awaiting an update.

mark_updated(key: str, 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

abstract async get(key: str) → CacheEntry | None

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

abstract async offer(key: str, entry: CacheEntry) → None

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

abstract 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: CacheStorage

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

async get(key: str) → CacheEntry | None

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

async offer(key: str, entry: CacheEntry) → None

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

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: Callable | None = None, configuration: CacheConfiguration = None, 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