bx_extras.lrucache module

a simple LRU (Least-Recently-Used) cache module

This module provides very simple LRU (Least-Recently-Used) cache functionality.

An in-memory cache is useful for storing the results of an ‘expensive’ process (one that takes a lot of time or resources) for later re-use. Typical examples are accessing data from the filesystem, a database, or a network location. If you know you’ll need to re-read the data again, it can help to keep it in a cache.

You can use a Python dictionary as a cache for some purposes. However, if the results you’re caching are large, or you have a lot of possible results, this can be impractical memory-wise.

An LRU cache, on the other hand, only keeps _some_ of the results in memory, which keeps you from overusing resources. The cache is bounded by a maximum size; if you try to add more values to the cache, it will automatically discard the values that you haven’t read or written to in the longest time. In other words, the least-recently-used items are discarded. [1]_

exception bx_extras.lrucache.CacheKeyError

Bases: KeyError

Error raised when cache requests fail

When a cache record is accessed which no longer exists (or never did), this error is raised. To avoid it, you may want to check for the existence of a cache record before reading or deleting it.

bx_extras.lrucache.DEFAULT_SIZE = 16

Default size of a new LRUCache object, if no ‘size’ argument is given.

class bx_extras.lrucache.LRUCache(size=16)

Bases: object

Least-Recently-Used (LRU) cache.

Instances of this class provide a least-recently-used (LRU) cache. They emulate a Python mapping type. You can use an LRU cache more or less like a Python dictionary, with the exception that objects you put into the cache may be discarded before you take them out.

Some example usage:

cache = LRUCache(32) # new cache cache[‘foo’] = get_file_contents(‘foo’) # or whatever

if ‘foo’ in cache: # if it’s still in cache…

# use cached version

contents = cache[‘foo’]

else:

# recalculate

contents = get_file_contents(‘foo’)

# store in cache for next time

cache[‘foo’] = contents

print cache.size # Maximum size

print len(cache) # 0 <= len(cache) <= cache.size

cache.size = 10 # Auto-shrink on size assignment

for i in range(50): # note: larger than cache size

cache[i] = i

if 0 not in cache: print ‘Zero was discarded.’

if 42 in cache:

del cache[42] # Manual deletion

for j in cache: # iterate (in LRU order)

print j, cache[j] # iterator produces keys, not values

mtime(key)

Return the last modification time for the cache record with key. May be useful for cache instances where the stored values can get ‘stale’, such as caching file or network resource contents.

size

Maximum size of the cache. If more than ‘size’ elements are added to the cache, the least-recently-used ones will be discarded.