cacheout 0.5.0

A caching library for Python

A caching library for Python.

Links

• Project: https://github.com/dgilland/cacheout

• Documentation: https://cacheout.readthedocs.io

• PyPI: https://pypi.python.org/pypi/cacheout/

• TravisCI: https://travis-ci.org/dgilland/cacheout

Features

• In-memory caching using dictionary backend

• Cache manager for easily accessing multiple cache objects

• Reconfigurable cache settings for runtime setup when using module-level cache objects

• Maximum cache size enforcement

• Default cache TTL (time-to-live) as well as custom TTLs per cache entry

• Bulk set, get, and delete operations

• Thread safe

• Multiple cache implementations: - LRU (Least Recently Used) - MRU (Most Recently Used) - LFU (Least Frequently Used) - RR (Random Replacement) - more coming soon!

Roadmap

• Additional cache implementations:

  • LIFO (Last In, First Out)

• Memoization decorator

• Layered caching (multi-level caching)

• Cache event listener support (e.g. on-get, on-set, on-delete)

• Regular expression support in cache get

• Set-on-missing callback support in cache get

• Cache statistics (e.g. cache hits/misses, cache frequency, etc)

Requirements

• Python >= 3.4

Quickstart

Install using pip:

pip install cacheout

Let’s start with some basic caching by creating a cache object:

from cacheout import Cache

cache = Cache()

By default the cache object will have a maximum size of 300 and TTL expiration turned off. These values can be set with:

cache = Cache(maxsize=300, ttl=0, timer=time.time)  # defaults

Set a cache key using cache.set():

cache.set(1, 'foobar')

Get the value of a cache key with cache.get():

assert cache.get(1) == 'foobar'

Set the TTL (time-to-live) expiration when caching:

cache.set(3, {'data': {}}, ttl=1)
assert cache.get(3) == {'data': {}}
time.sleep(1)
assert cache.get(3) is None

Get a copy of the entire cache with cache.copy():

assert cache.copy() == {1: 'foobar', 2: ('foo', 'bar', 'baz')}

Delete a cache key with cache.delete():

cache.delete(1)
assert cache.get(1) is None

Clear the entire cache with cache.clear():

cache.clear()
assert len(cache) == 0

Perform bulk operations with cache.set_many(), cache.get_many(), and cache.delete_many():

cache.set_many({'a': 1, 'b': 2, 'c': 3})
assert cache.get_many(['a', 'b', 'c']) == {'a': 1, 'b': 2, 'c': 3}
cache.delete_many(['a', 'b', 'c'])
assert cache.count() == 0

Reconfigure the cache object after creation with cache.configure():

cache.configure(maxsize=1000, ttl=5 * 60)

Get keys, values, and items from the cache with cache.keys(), cache.values(), and cache.items():

cache.set_many({'a': 1, 'b': 2, 'c': 3})
assert list(cache.keys()) == ['a', 'b', 'c']
assert list(cache.values()) == [1, 2, 3]
assert list(cache.items()) == [('a', 1), ('b', 2), ('c', 3)]

Iterate over cache keys:

for key in cache:
    print(key, cache.get(key))
    # 'a' 1
    # 'b' 2
    # 'c' 3

Check if key exists with cache.has() and key in cache:

assert cache.has('a')
assert 'a' in cache

Manage multiple caches using CacheManager:

from cacheout import CacheManager

cacheman = CacheManager({'a': {'maxsize': 100},
                         'b': {'maxsize': 200, 'ttl': 900},
                         'c': {})

cacheman['a'].set('key1', 'value1')
value = cacheman['a'].get('key')

cacheman['b'].set('key2', 'value2')
assert cacheman['b'].maxsize == 200
assert cacheman['b'].ttl == 900

cacheman['c'].set('key3', 'value3')

cacheman.clear_all()
for name, cache in cacheman:
    assert name in cacheman
    assert len(cache) == 0

For more details, see the full documentation at https://cacheout.readthedocs.io.

Changelog

v0.5.0 (2018-02-04)

• Add LFUCache

• Delete expired items before popping an item in Cache.popitem().

v0.4.0 (2018-02-02)

• Add MRUCache

• Add RRCache

• Add Cache.popitem().

• Rename Cache.expirations() to Cache.expire_times(). (breaking change)

• Rename Cache.count() to Cache.size(). (breaking change)

• Remove minimum arguement from Cache.evict(). (breaking change)

v0.3.0 (2018-01-31)

• Add LRUCache.

• Add CacheManager.__repr__().

• Make threading lock usage in Cache more fine-grained and eliminate redundant locking.

• Fix missing thread-safety in Cache.__len__() and Cache.__contains__().

v0.2.0 (2018-01-30)

• Rename Cache.setup() to Cache.configure(). (breaking change)

• Add CacheManager class.

v0.1.0 (2018-01-28)

• Add Cache class.