caches 0.2.9

Interface

All caches caching classes have a similar interface, they take passed in constructor *args and concat them to create a key:

c = KeyCache('foo', 'bar', 'che')
print c.key # foo.bar.che

If you would like to init your cache object with a value, use the data **kwarg:

c = KeyCache('foo', data="boom!")
print c.key # foo
print c # "boom!"

Each class is meant to be extended so you can set some parameters:

• serialize – boolean – True if you want all values pickled, False if you don’t (ie, you’re caching ints or strings or something).

• prefix – string – This will be prepended to the key args you pass into the constructor.

• ttl – integer – time to live, how many seconds to cache the value. Set to like 2 hours by default, 0 means live forevor.

• connection_name – string – if you have more than one caches dsn then you can use this to set the name of the connection you want (the name of the connection is the #connection_name fragment of a dsn url).

class MyIntCache(KeyCache):
  serialize = False # don't bother to serialize values since we're storing ints
  prefix = "MyIntCache" # every key will have this prefix, change to invalidate all current cache
  ttl = 7200 # store each int for 2 hours

Cache Classes

c = KeyCache('foo')
c.data = 5 # cache 5
c += 10 # increment 5 by 10, store 15 in the cache

c = DictCache('foo')
c['bar'] = 'b'
c['che'] = 'c'
for key, val in c.iteritems():
  print key, val # will print bar b and then che c

c = SetCache('foo')
c.add('bar')
c.add('che')
print 'che' in c # True

c = SortedSetCache('foo')
c.add('bar', 1)
c.add('che', 10)
print 'che' in c # True
print c.pop() # (bar, 1)

c = CounterCache('foo')
c['bar'] = 5
c['bar'] += 5

print c['bar'] # 10

Decorator

Caches exposes a decorator to make caching the return value of a function easy. This only works for KeyCache derived caching.

The cached decorator can accept a caching class (defaults to KeyCache) and also a key function (similar to the sorted() key argument, except caches key argument returns a list that can be passed to the constructor of the caching class as *args.

from caches import KeyCache
from caches.decorators import cached

@cached(key="some_cache_key")
def foo(*args):
    return reduce(lambda x, y: x+y, args)

foo(1, 2) # will compute the value and cache the return value
foo(1, 2) # return value from cache

foo(1, 2, 3) # uh-oh, wrong value, our key was too static

# let's try again, this time with a dynamic key
@cached(key=lambda *args: args)
def foo(*args):
    return reduce(lambda x, y: x+y, args)

foo(1, 2) # compute and cache, key func returned [1, 2]
foo(1, 2) # grabbed from cache
foo(1, 2, 3) # compute and cache because our key func returned [1, 2, 3]

# what about custom caches classes?
class CustomCache(KeyCache): pass

@cached(CustomCache, key=lambda *args: args)
def foo(*args):
    return reduce(lambda x, y: x+y, args)