Overview

cache3 supports both memory and disk cache backends.

memory-based cache has good performance but does not support data persistence.

disk-based caches support persistence but have slightly lower performance.

Regardless of which cache is used, they all follow the same API, which means that the backend implementation of the cache can be switched at will without cost.

The built-in cache policies are LRU, LFU, FIFO, and if these don’t meet your needs, you can extend them with manager.

Installation

To use cache3, first install it using pip:

$ pip install -U cache3

or download source and install

$ git clone https://github.com/StKali/cache3.git
$ cd cache3
$ python setup.py install

Quick start

Creating a cache is so easy, and all cache parameters are set to conservative defaults. Default is a good choice if you don’t want too much detail, but it’s not guaranteed to be efficient.

In class docs you can know more detailed parameters and configuration information.

In [1]: from cache3 import SafeCache
In [2]: cache = SafeCache()

# Default cache name: `default.cache3`, timeout:300s
In [3]: cache
Out[3]: <SafeCache name=default.cache3 timeout=300.00>

# Default max size  1 << 24 (16M)
In [4]: cache.max_size
Out[4]: 16777216

# Default key evict policy
In [5]: cache.evict
Out[5]: 'lru_evict'

set, get, delete(del), has_key(in)

set an item, get a value, and delete a key using the usual operators:

In [6]: cache['name'] = 'clark monkey'

In [7]: cache['name']     # get name
Out[7]: 'clark monkey'

In [8]: del cache['name']     # delete key from cache

In [9]: 'name' in cache    # default tag
Out[9]: False

The dictionary-like operation is simple, but the tag and timeout cannot be specified. If you want to specify these parameters, get, set, ex_set, delete are good choices.

# set item
In [10]: cache.set('name', 'venus')
Out[10]: True

# get ttl
In [11]: cache.ttl('name')
Out[11]: 299.01095983695984

# Get value
In [12]: cache.get('name')
Out[12]: 'venus'

# Delete
In [13]: cache.delete('name')
Out[13]: True

# Has key
In [14]: cache.has_key('name')
Out[14]: False

Use tag to group keys, which allows key duplication.

# Set item with tag
In [15]: cache.set('name', 'venus', tag='class:1')
Out[15]: True

In [16]: cache.set('name', 'apollo', tag='class:2')
Out[16]: True

# If tag is not specified, the value cannot be found correctly
# Tag is similar to namespace, keys are divided into spaces by tag
In [17]: cache.get('name')

In [18]: cache.get('name', tag='class:1')
Out[18]: 'venus'

In [19]: cache.get('name', tag='class:2')
Out[19]: 'apollo'

# Set item with timeout
In [20]: cache.set('count', 30, timeout=60, tag='class:1')
Out[20]: True

In [21]: cache.ttl('count', tag='class:1')
Out[21]: 59.076417922973633

ex_set

It ensures set is safety through exclusive locks. SafeCache uses threading.Lock, and disk-based cache uses file locks, so they are process-safe.

# clear the cache
In [22]: cache.clear()

In [23]: cache.set('name', 'venus')
Out[23]: True

# Mutex set item
In [24]: cache.ex_set('name', 'apollo')
Out[24]: False

# Delete the item and try again
In [25]: cache.delete('name')
Out[25]: True

# Reset success
In [26]: cache.ex_set('name', 'apollo')
Out[26]: True

get_many

Get many items at one time, support tag parameter, and only one tag can be specified

# Clear the cache
In [27]: cache.clear()

# Set items
In [28]: for i in range(3):
    ...:     cache.set(i, i, tag='test:get_many')
    ...:
In [29]: cache.get_many([i for i in range(3)], tag='test:get_many')
Out[29]: {0: 0, 1: 1, 2: 2}

memoize

Note

memoize This decorator is insensitive to parameters.

from cache3 import SimpleCache

cache: SimpleCache = SimpleCache()

@cache.memoize(timeout=10, tag='cached:page')
def query_pages() -> bytes:
    return b'<h1> Hello Cache3 </h1>'

# Note: This decorator is insensitive to parameters.

inspect

inspect can obtain almost all the information of the key. Because the storage backend is unknown, there are differences between different implementations.

• Memory backend

#  Based memory cache
In [1]: cache: SafeCache = SafeCache()
In [2]: cache['name'] = 'Venus'
In [3]: cache.inspect('name')
Out[3]: {
 'key': 'name',
 'store_key': 'name:default',
 'store_value': 'Venus',
 'value': 'Venus',
 'expire': 1644718648.995299
}

• Disk backend

#  Based disk cache
In [1]: cache: DiskCache = DiskCache()
In [2]: cache['name'] = 'Ares'
In [3]: cache.inspect('name')
Out[3]: {
    'key': 'name',
    'store': 1644718388.4478312,
    'expire': 1644718688.4478312,
    'access': 1644718388.4478312,
    'access_count': 0,
    'tag': 'default',
    'value': 'cache3',
    'store_key': 'name',
    'serial_value': 'Ares'
}

others

Some APIs that are not commonly used but are very useful: ttl, touch, clear

# Get the ttl
In [1]: cache.ttl('name')
Out[1]: 297.9396250247955

# touch
# Touch the key and reset ttl
In [2]: cache.touch('name', 100)
Out[2]: True
In [3]: cache.ttl('name')
Out[3]: 98.66487669944763

iterable

# It's iterable.
In [1]: for i in range(3):
...:     cache.set(i, i, tag='test:get_many')
...:
In [2]: list(cache)
Out[2]: [(0, 0, 'default'), (1, 1, 'default'), (2, 2, 'default')]

In [3]: tuple(cache)
Out[3]: ((0, 0, 'default'), (1, 1, 'default'), (2, 2, 'default'))

memory-based cache

Memory-based caches will completely lose the data in the cache when the program crashes or exits, in other words, they do not support data persistence.

MiniCache

SimpleCache is a thread-unsafe cache, which aims to provide high performance but does not guarantee data safety under multi-threading. SafeCache is a good choice if you want thread safety.

Cache

SafeCache is a thread-safe cache. It has exactly the same implementation as SimpleCache, based on Python’s OrderedDict, the difference is the type of Lock, SimpleCache Lock is an empty lock, while SafeCache uses threading.Lock to ensure its thread safety.

disk-based cache

The disk-based cache backend is implemented in SQLite3 because it is lightweight enough and performs well.

Note

Since the disk cache is based on SQLite3, even after a series of optimizations, it still needs to be carefully considered whether it will become a concurrency bottleneck. In fact, in most cases it is sufficient.

DiskCache

DiskCache overrides SimpleDiskCache’s serialize() and deserialize() methods by inheriting PickleMixin mixins to support more data types, but has no difference with SimpleDiskCache.

class DiskCache(PickleMixin, SimpleDiskCache):

• JsonDiskCache