Cache layer
Pyvot must assume that the contents of an Excel workbook can change at any time, due to interactive manipulation or other external influences. Living out of process, this can be a performance catastrophe. We use a cache when possible, on the assumption that Excel doesn’t change during any single call into to the Pyvot user API.
This module provides the @cache_result() decorator which adds caching to a function or property, an @enable_caching() decorator for enabling the (off by default) cache for the duration of a function call, and the CacheManager, for non-decorator cache control including invalidation.
Singleton CacheManager used by all of Pyvot
Singleton manager for the program’s CacheSites (created through use of @:func:cache_result) Cache state is dynamically scoped on the stack by use of a context manager:
with CacheManager.caching_enabled():
do_stuff()
Within that context, all @cache_result decorators are enabled and may store / return cached values Cached values are deleted when the context is exited.
The context may be safely nested.
Returns a tuple (site group key, group size, hits, misses, uncached misses) per cache site group. (uncached misses refers to those misses that occurred without caching enabled (see CacheManager.is_caching_enabled) A cache site group is an aggregation of cache sites that are considered meaningfully related, with regards to performance counters.
For example, though a method on a class has a cache site per _instance_, all instance sites of a method are joined to the same site group.
Returns an object implementing the context-manager protocol. Within the context, caching is disabled. When exiting the context, the cache-enable state (incl. nesting level) is restored to its previous value. Entering the context immediately invalidates all cache sites
with xl.CacheManager.caching_enabled():
with xl.CacheManager.caching_disabled():
assert not xl.CacheManager.is_caching_enabled()
assert xl.CacheManager.is_caching_enabled()
Returns an object implementing the context-manager protocol. Within the context, caching is enabled (this is a context-manager version of the @enable_caching decorator).
Cache activation may be nested; there is no harm in enabling caching before calling a function which does the same:
with xl.CacheManager.caching_enabled():
with xl.CacheManager.caching_enabled():
assert xl.CacheManager.is_caching_enabled()
assert xl.CacheManager.is_caching_enabled()
assert not xl.CacheManager.is_caching_enabled()
Creates a CacheSite instanced, managed by this CacheManager. The manager keeps a weak reference to the site ; the lifetime of the cache is controlled by the caller
The site_group_key specifies the key on which to aggregate hit / miss stats in cache_info() Note that a reference to site_group_key will continue to be held by the CacheManager, so take care to select keys that are small in size, or wouldn’t be garbage collected anyway (i.e. a module-level class)
Invalidates cache sites program-wide. This method should be called whenever the Excel COM API is used to modify a workbook (for example, it is called by xl.range.Range.set()).
Alternatively, one can use caching_disabled(), since it invalidates caches on context entry.
Represents a single cache of arguments -> results. Note that there can be multiple cache sites per @cache_result-wrapped method; each instance with the caching method uses a separate cache site
Container for hits, misses, and uncached_misses (misses that occurred with cachind disabled). Accessed as CacheSite.stats
Decorator class for caching the results of method calls / read-only properties. The cache is controlled by the state of the singleton CacheManager. While caching is enabled, the wrapped function / property is called only once per unique set of arguments, and the return value is stored to satisfy future calls with those same arguments. When caching is disabled, all cached values are cleared, and the wrapped function is always called.
This decorator may only be applied to a method or property within a class. A separate cache is maintained per instance; although argument sets are typically compared for value equality, two equal instances still have separate caches.
Cache statistics are available via the ‘stats’ attribute (unless wrapping a property):
instance_a.cached_method -> CacheSite instance instance_a.cached_method.stats.hits -> # of cache hits (similarly for misses) instance_b.cached_method -> Different CacheSite instance
This information is summarized by CacheManager.cache_info(), in which the per-instance stats are aggregated by class
Decorator which enables caching within the wrapped function. Caching is enabled until the function exits; i.e. functions called directly or indirectly will also have caching enabled.