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
[source]¶ Bases:
object
Provides configuration for cache.
-
configured
() → bool[source]¶ Cache will raise NotConfiguredCacheCalledException if this returns false. May be useful if when cache is reconfigured in runtime.
-
entry_builder
() → memoize.entrybuilder.CacheEntryBuilder[source]¶ Determines which CacheEntryBuilder is to be used by cache.
-
eviction_strategy
() → memoize.eviction.EvictionStrategy[source]¶ Determines which EvictionStrategy is to be used by cache.
-
key_extractor
() → memoize.key.KeyExtractor[source]¶ Determines which KeyExtractor is to be used by cache.
-
-
class
memoize.configuration.
DefaultInMemoryCacheConfiguration
[source]¶ Bases:
memoize.configuration.CacheConfiguration
Default parameters that describe in-memory cache. Be ware that parameters used do not suit every case.
-
configured
() → bool[source]¶ Cache will raise NotConfiguredCacheCalledException if this returns false. May be useful if when cache is reconfigured in runtime.
-
entry_builder
() → memoize.entrybuilder.ProvidedLifeSpanCacheEntryBuilder[source]¶ Determines which CacheEntryBuilder is to be used by cache.
-
eviction_strategy
() → memoize.eviction.LeastRecentlyUpdatedEvictionStrategy[source]¶ Determines which EvictionStrategy is to be used by cache.
-
key_extractor
() → memoize.key.EncodedMethodReferenceAndArgsKeyExtractor[source]¶ Determines which KeyExtractor 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)[source]¶ 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[source]¶ Cache will raise NotConfiguredCacheCalledException if this returns false. May be useful if when cache is reconfigured in runtime.
-
entry_builder
() → memoize.entrybuilder.CacheEntryBuilder[source]¶ Determines which CacheEntryBuilder is to be used by cache.
-
eviction_strategy
() → memoize.eviction.EvictionStrategy[source]¶ Determines which EvictionStrategy is to be used by cache.
-
static
initialized_with
(configuration: memoize.configuration.CacheConfiguration) → memoize.configuration.MutableCacheConfiguration[source]¶
-
key_extractor
() → memoize.key.KeyExtractor[source]¶ Determines which KeyExtractor is to be used by cache.
-
method_timeout
() → datetime.timedelta[source]¶ Defines how much time wrapped method can take to complete.
-
set_entry_builder
(value: memoize.entrybuilder.CacheEntryBuilder) → memoize.configuration.MutableCacheConfiguration[source]¶
-
set_eviction_strategy
(value: memoize.eviction.EvictionStrategy) → memoize.configuration.MutableCacheConfiguration[source]¶
-
set_key_extractor
(value: memoize.key.KeyExtractor) → memoize.configuration.MutableCacheConfiguration[source]¶
-
set_method_timeout
(value: datetime.timedelta) → memoize.configuration.MutableCacheConfiguration[source]¶
-
memoize.entry module¶
[Internal use only] Contains implementation of cache entry.
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.
ProvidedLifeSpanCacheEntryBuilder
(update_after: datetime.timedelta = datetime.timedelta(seconds=600), expire_after: datetime.timedelta = datetime.timedelta(seconds=1800))[source]¶ Bases:
memoize.entrybuilder.CacheEntryBuilder
CacheEntryBuilder which uses constant delays independent form values that are cached
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
[source]¶ Bases:
object
-
mark_read
(key: str) → None[source]¶ Informs strategy that entry related to given key was read by current client.
-
mark_released
(key: str) → None[source]¶ Informs strategy that entry related to given key was deemed non-essential by current client.
-
-
class
memoize.eviction.
LeastRecentlyUpdatedEvictionStrategy
(capacity=4096)[source]¶ Bases:
memoize.eviction.EvictionStrategy
-
mark_read
(key: str) → None[source]¶ Informs strategy that entry related to given key was read by current client.
-
mark_released
(key: str) → None[source]¶ Informs strategy that entry related to given key was deemed non-essential by current client.
-
-
class
memoize.eviction.
NoEvictionStrategy
[source]¶ Bases:
memoize.eviction.EvictionStrategy
Strategy to be used when delegating eviction to cache itself. This strategy performs no actions.
-
mark_read
(key: str) → None[source]¶ Informs strategy that entry related to given key was read by current client.
-
mark_released
(key: str) → None[source]¶ Informs strategy that entry related to given key was deemed non-essential by current client.
-
memoize.exceptions module¶
[API] Contains exceptions that may be exposed to the library client.
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)[source]¶ 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.
-
class
memoize.key.
EncodedMethodReferenceAndArgsKeyExtractor
[source]¶ 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).
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')[source]¶ Bases:
memoize.serde.SerDe
Applies extra encoding to the data (for instance compression when ‘zip’ or ‘bz2’ codec used).
-
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>>)[source]¶ 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.
-
class
memoize.serde.
PickleSerDe
(pickle_protocol=4)[source]¶ Bases:
memoize.serde.SerDe
Uses encoded pickles as binary representation.
memoize.statuses module¶
[Internal use only] Encapsulates update state management.
-
class
memoize.statuses.
UpdateStatuses
(update_lock_timeout: datetime.timedelta = datetime.timedelta(seconds=300))[source]¶ Bases:
object
-
await_updated
(key: str) → Optional[memoize.entry.CacheEntry][source]¶ 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[source]¶ 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[source]¶ 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.
-
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
[source]¶ Bases:
object
-
get
(key: str) → Optional[memoize.entry.CacheEntry][source]¶ Request value for given key. If currently there is no such value, returns None. Has to be async.
-
-
class
memoize.storage.
LocalInMemoryCacheStorage
[source]¶ 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][source]¶ Request value for given key. If currently there is no such value, returns None. 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)[source]¶ 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
Raises: CachedMethodFailedException upon call: if cached method timed-out or thrown an exception
Raises: NotConfiguredCacheCalledException upon call: if provided configuration is not ready