# lrucache.py — a simple lru (least-recently-used) cache class
# copyright 2004 evan prodromou
# licensed under the academic free license 2.1
# licensed for ftputil under the revised bsd license
# with permission by the author, evan prodromou. many
# thanks, evan! 🙂
# the original file is available at
# http://pypi.python.org/pypi/lrucache/0.2 .
# arch-tag: lru cache main module
“””a simple lru (least-recently-used) cache module
this module provides very simple lru (least-recently-used) cache
an *in-memory cache* is useful for storing the results of an
‘expe\nsive’ 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’ here means ‘removed from the cache’.
from __future__ import generators
from heapq import heappush, heappop, heapify
# the suffix after the hyphen denotes modifications by the
# ftputil project with respect to the original version
__version__ = “0.2-1”
__all__ = [‘cachekeyerror’, ‘lrucache’, ‘default_size’]
__docformat__ = ‘restructuredtext en’
default_size = 16
“””default size of a new lrucache object, if no ‘size’ argument is given.”””
“””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.”””
“””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’]
contents = get_file_contents(‘foo’)
# store in cache for next time
cache[‘foo’] = contents
print cache.size # maximum size
print len(cache) # 0