Skip to main content

A caching library for Python

Project description

version travis coveralls license

A caching library for Python.

Features

  • In-memory caching using dictionary backend

  • Cache manager for easily accessing multiple cache objects

  • Maximum cache size enforcement

  • Cache-level default TTL (time-to-live) as well as custom TTLs on a per cache entry basis

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

  • Bulk set, get, and delete operations

  • Thread-safe

Roadmap

  • Additional cache replacement policies:

    • LRU (Least Recently Used)

    • MRU (Most Recently Used)

    • LFU (Least Frequently Used)

    • LIFO (Last In, First Out)

    • RR (Random Replacement)

  • 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

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

Changelog

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cacheout-0.2.0.tar.gz (20.3 kB view hashes)

Uploaded Source

Built Distribution

cacheout-0.2.0-py3-none-any.whl (9.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page