pymor.core.cache

This module provides the caching facilities of pyMOR.

Any class that wishes to provide cached method calls should derive from CacheableObject. Methods which are to be cached can then be marked using the cached decorator.

To ensure consistency, CacheableObject derives from ImmutableObject: The return value of a cached method call should only depend on its arguments as well as the immutable state of the class instance.

Making this assumption, the keys for cache lookup are created from the following data:

1. the instance’s cache_id in case of a persistent CacheRegion, else the instance’s uid,

2. the method’s __name__,

3. the method’s arguments.

Note that instances of ImmutableObject are allowed to have mutable private attributes. It is the implementors responsibility not to break things. (See this warning.)

Backends for storage of cached return values derive from CacheRegion. Currently two backends are provided for memory-based and disk-based caching (MemoryRegion and DiskRegion). The available regions are stored in the module level cache_regions dict. The user can add additional regions (e.g. multiple disk cache regions) as required. CacheableObject.cache_region specifies a key of the cache_regions dict to select a cache region which should be used by the instance. (Setting cache_region to None or 'none' disables caching.)

By default, a ‘memory’, a ‘disk’ and a ‘persistent’ cache region are configured. The paths and maximum sizes of the disk regions, as well as the maximum number of keys of the memory cache region can be configured via the pymor.core.cache.default_regions.disk_path, pymor.core.cache.default_regions.disk_max_size, pymor.core.cache.default_regions.persistent_path, pymor.core.cache.default_regions.persistent_max_size and pymor.core.cache.default_regions.memory_max_keys defaults.

There two ways to disable and enable caching in pyMOR:

1. Calling disable_caching (enable_caching), to disable (enable) caching globally.

2. Calling CacheableObject.disable_caching (CacheableObject.enable_caching) to disable (enable) caching for a given instance.

Caching of a method is only active if caching has been enabled both globally (enabled by default) and on instance level. For debugging purposes, it is moreover possible to set the environment variable PYMOR_CACHE_DISABLE=1 which overrides any call to enable_caching.

A cache region can be emptied using CacheRegion.clear. The function clear_caches clears each cache region registered in cache_regions.

Module Contents

Classes

CacheRegion	Base class for all pyMOR cache regions.
MemoryRegion	Base class for all pyMOR cache regions.
DiskRegion	Base class for all pyMOR cache regions.
CacheableObject	Base class for anything that wants to use our built-in caching.

Functions

cleanup_non_persistent_regions
_safe_filename
default_regions
enable_caching	Globally enable caching.
disable_caching	Globally disable caching.
clear_caches	Clear all cache regions.
cached	Decorator to make a method of CacheableObject actually cached.
build_cache_key

Attributes

cache_regions
_caching_disabled
NoneType

pymor.core.cache.cleanup_non_persistent_regions()

pymor.core.cache._safe_filename(old_name)

class pymor.core.cache.CacheRegion

Base class for all pyMOR cache regions.

persistent

If True, cache entries are kept between multiple program runs.

abstract get(self, key)

Return cache entry for given key.

Parameters

key

The key for the cache entry.

Returns

(True, entry)

in case the key has been found in the cache region.

(False, None)

in case the key is not present in the cache region.

abstract set(self, key, value)

Set cache entry for key to given value.

This method is usually called only once for any given key (with the exemption of issues due to concurrency).

abstract clear(self)

Clear the entire cache region.

class pymor.core.cache.MemoryRegion(max_keys)

Bases: CacheRegion

Base class for all pyMOR cache regions.

persistent

If True, cache entries are kept between multiple program runs.

NO_VALUE

get(self, key)

Return cache entry for given key.

Parameters

key

The key for the cache entry.

Returns

(True, entry)

in case the key has been found in the cache region.

(False, None)

in case the key is not present in the cache region.

set(self, key, value)

Set cache entry for key to given value.

This method is usually called only once for any given key (with the exemption of issues due to concurrency).

clear(self)

Clear the entire cache region.

class pymor.core.cache.DiskRegion(path, max_size, persistent)

Bases: CacheRegion

Base class for all pyMOR cache regions.

persistent

If True, cache entries are kept between multiple program runs.

get(self, key)

Return cache entry for given key.

Parameters

key

The key for the cache entry.

Returns

(True, entry)

in case the key has been found in the cache region.

(False, None)

in case the key is not present in the cache region.

set(self, key, value)

Set cache entry for key to given value.

This method is usually called only once for any given key (with the exemption of issues due to concurrency).

clear(self)

Clear the entire cache region.

pymor.core.cache.default_regions(disk_path=os.path.join(tempfile.gettempdir(), 'pymor.cache.' + getpass.getuser()), disk_max_size=1024 ** 3, persistent_path=os.path.join(tempfile.gettempdir(), 'pymor.persistent.cache.' + getpass.getuser()), persistent_max_size=1024 ** 3, memory_max_keys=1000)

pymor.core.cache.cache_regions

pymor.core.cache._caching_disabled

pymor.core.cache.enable_caching()

Globally enable caching.

pymor.core.cache.disable_caching()

Globally disable caching.

pymor.core.cache.clear_caches()

Clear all cache regions.

class pymor.core.cache.CacheableObject

Bases: pymor.core.base.ImmutableObject

Base class for anything that wants to use our built-in caching.

cache_region

Name of the CacheRegion to use. Must correspond to a key in the cache_regions dict. If None or 'none', caching is disabled.

cache_id

Identifier for the object instance on which a cached method is called.

disable_caching(self)

Disable caching for this instance.

enable_caching(self, region, cache_id=None)

Enable caching for this instance.

Warning

Note that using with_ will reset cache_region and cache_id to their class defaults.

Parameters

region

Name of the CacheRegion to use. Must correspond to a key in the cache_regions dict. If None or 'none', caching is disabled.

cache_id

Identifier for the object instance on which a cached method is called. Must be specified when region is persistent. When region is not persistent and no cache_id is given, the object’s uid is used instead.

cached_method_call(self, method, *args, **kwargs)

Call a given method and cache the return value.

This method can be used as an alternative to the cached decorator.

Parameters

method

The method that is to be called. This has to be a method of self.

args

Positional arguments for method.

kwargs

Keyword arguments for method

Returns

The (possibly cached) return value of method(*args, **kwargs).

_cached_method_call(self, method, pass_self, argnames, defaults, args, kwargs)

pymor.core.cache.cached(function)

Decorator to make a method of CacheableObject actually cached.

pymor.core.cache.NoneType

pymor.core.cache.build_cache_key(obj)