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