API#

Cache3 is a MIT licensed safe and lightweight cache library, written in pure-Python.

MiniCache#

class cache3.MiniCache(name: str, max_size: int = 1073741824, evict_size: int = 16, evict_policy: str = 'lru', thread_safe: bool = True)#

A simple dictionary-based in-memory cache that supports automatic data elimination and does not support tag.

Cache is built based on minicache, but cache is tag-supported.

__init__(name: str, max_size: int = 1073741824, evict_size: int = 16, evict_policy: str = 'lru', thread_safe: bool = True) → None#

__repr__() → str#: Return repr(self).

incr(key: Any, delta: int | float = 1) → int | float#: Increases the value by delta (default 1)

inspect(key: Any) → Dict[str, Any] | None#: inspect the key in cache informations, returns the dict if the key is existed else None

memoize(timeout: int | float | None = None) → Callable[[str | None, int | float | None], Callable]#: The cache is decorated with the return value of the function, and the timeout is available.

ttl(key: Any) → int | float | None#

returns the key time to live

Returns:: the key has been expired None : never expired float: life seconds
Return type:: -1

Cache#

class cache3.Cache(name: str, *args, **kwargs)#

Memory-based cache instance

__init__(name: str, *args, **kwargs) → None#

__repr__() → str#: Return repr(self).

memoize(timeout: int | float | None = 86400, tag: str | None = None) → Any#: The cache is decorated with the return value of the function, and the timeout is available.

DiskCache#

class cache3.DiskCache(directory: str = '~/.cache3', name: str = 'default.sqlite3', max_size: int = 1073741824, iter_size: int = 256, evict_policy: str = 'lru', evict_size: int = 64, evict_time: int | float = 2, charset: str | None = None, protocol: int = 5, raw_max_size: int = 131072, isolation: str | None = None, timeout: int | float | None = 600, pragmas: Dict[str, Any] | None = None)#

Disk cache based on sqlite and file system

__contains__(key: Any, tag: str | None = None) → bool#: Return True if the key in cache else False.

__delitem__(key: Any, tag: str | None = None) → bool#

Parameters:

key –
tag –

Returns:

__getitem__(key: Any, default: Any | None = None, tag: str | None = None) → Any#

Parameters:

key –
default –
tag –

Returns:

__init__(directory: str = '~/.cache3', name: str = 'default.sqlite3', max_size: int = 1073741824, iter_size: int = 256, evict_policy: str = 'lru', evict_size: int = 64, evict_time: int | float = 2, charset: str | None = None, protocol: int = 5, raw_max_size: int = 131072, isolation: str | None = None, timeout: int | float | None = 600, pragmas: Dict[str, Any] | None = None) → None#

__iter__(tag: str | None = <class 'cache3.util.empty'>) → Iterable[Tuple[Any, str]]#: Returns all keys when tag is specified, otherwise it returns both key and tag

__repr__() → str#: Return repr(self).

__setitem__(key: Any, value: Any, timeout: int | float | None = None, tag: str | None = None) → bool#

Parameters:

key –
value –
timeout –
tag –

Returns:

clear() → bool#: Delete all data and initialize the statistics table.

delete(key: Any, tag: str | None = None) → bool#

Parameters:

key –
tag –

Returns:

ex_set(key: Any, value: Any, timeout: int | float | None = None, tag: str | None = None) → bool#: Write the key-value relationship when the data does not exist in the cache, otherwise the set operation will be cancelled

get(key: Any, default: Any | None = None, tag: str | None = None) → Any#

Parameters:

key –
default –
tag –

Returns:

get_many(keys: List[Any], tag: str | None = None) → Dict[Any, Any]#

There is a limitation on obtaining a group of key values.

TODO WARNING: the tags of this group of key values must be consistent,: but the memory based cache strategy does not have this limitation. This feature will be supported in the future to ensure the consistency of behavior

has_key(key: Any, tag: str | None = None) → bool#: Return True if the key in cache else False.

incr(key: Any, delta: int | float = 1, tag: str | None = None) → int | float#

Increases the value by delta (default 1)

int, float and (str/bytes) not serialize, so add in sql statement.

The increment operation should be implemented through SQLite, which is not safe at the Python language level

Parameters:

key – key literal value
delta – Increase in size

Returns:

The new value

Raises:

KeyError – if the key does not exist or has been eliminated
TypeError – if value is not a number type

inspect(key: Any, tag: str | None = None) → Dict[str, Any] | None#: Get the details of the key value, including any information, access times, recent access time, etc., and even the underlying serialized data

items(tag: str | None = <class 'cache3.util.empty'>) → Iterable[Tuple]#

Returns all key-value relationships under the tag namespace in the cache database when tag is specified. Otherwise, all key-value-tags in the database are returned.

Note: that whether tag is specified or not will determine the difference in the return value

keys(tag: str | None = <class 'cache3.util.empty'>) → Iterable[Tuple[Any, str]]#: Returns all keys when tag is specified, otherwise it returns both key and tag

memoize(timeout: int | float | None = 86400, tag: str | None = None) → Any#: The cache is decorated with the return value of the function, and the timeout is available.

pop(key: Any, default: Any | None = None, tag: str | None = None) → Any#

Parameters:

key –
default –
tag –

Returns:

set(key: Any, value: Any, timeout: int | float | None = None, tag: str | None = None) → bool#

Parameters:

key –
value –
timeout –
tag –

Returns:

touch(key: Any, timeout: int | float | None = None, tag: str | None = None) → bool#: Renew the key. When the key does not exist, false will be returned

try_evict(sql) → None#: try to evict expired data

ttl(key: Any, tag: str | None = None) → int | float | None#

Parameters:

key –
tag –

Returns:

values(tag: str | None = <class 'cache3.util.empty'>) → Iterable[Tuple]#: Returns all values when tag is specified, otherwise it returns both value and tag