Cache#
The cache module provides the Cache
class which is used as the base for all other cache
types.
- class cacheout.cache.Cache(*, maxsize: int = 256, ttl: int | float = 0, timer: ~typing.Callable[[], int | float] = <built-in function time>, default: ~typing.Any = None, enable_stats: bool = False, on_get: ~typing.Callable[[~typing.Hashable, ~typing.Any, bool], None] | None = None, on_set: ~typing.Callable[[~typing.Hashable, ~typing.Any, ~typing.Any], None] | None = None, on_delete: ~typing.Callable[[~typing.Hashable, ~typing.Any, ~cacheout.cache.RemovalCause], None] | None = None)[source]#
An in-memory, FIFO cache object.
It supports:
Maximum number of cache entries
Global TTL default
Per cache entry TTL
TTL first/non-TTL FIFO cache eviction policy
Cache entries are stored in an
OrderedDict
so that key ordering based on the cache type can be maintained without the need for additional list(s). Essentially, the key order of theOrderedDict
is treated as an “eviction queue” with the convention that entries at the beginning of the queue are “newer” while the entries at the end are “older” (the exact meaning of “newer” and “older” will vary between different cache types). When cache entries need to be evicted, expired entries are removed first followed by the “older” entries (i.e. the ones at the end of the queue).- maxsize#
Maximum size of cache dictionary. Defaults to
256
.
- ttl#
Default TTL for all cache entries. Defaults to
0
which means that entries do not expire. Time units are determined bytimer
function. Default units are in seconds.
- timer#
Timer function to use to calculate TTL expiration. Defaults to
time.time
where TTL units are in seconds.
- default#
Default value or function to use in
get()
when key is not found. If callable, it will be passed a single argument,key
, and its return value will be set for that cache key.
- on_get#
Callback which will be executed when a cache entry is retrieved. See
T_ON_GET_CALLBACK
for details.
- on_set#
Callback which will be executed when a cache entry is set. See
T_ON_SET_CALLBACK
for details.
- on_delete#
Callback which will be executed when a cache entry is removed. See
T_ON_DELETE_CALLBACK
for details.
- stats#
Cache statistics.
- add(key: Hashable, value: Any, ttl: int | float | None = None) None [source]#
Add cache key/value if it doesn’t already exist.
This method ignores keys that exist which leaves the original TTL in tact.
- add_many(items: Mapping, ttl: int | float | None = None) None [source]#
Add multiple cache keys at once.
- configure(*, maxsize: int | None = None, ttl: int | float | None = None, timer: ~typing.Callable[[], int | float] | None = None, default: ~typing.Any = <object object>, enable_stats: ~typing.Any = <object object>) None [source]#
Configure cache settings.
This method is meant to support runtime level configurations for global level cache objects.
- delete(key: Hashable) int [source]#
Delete cache key and return number of entries deleted (
1
or0
).- Parameters:
key – Cache key to delete.
- Returns:
1
if key was deleted,0
if key didn’t exist.- Return type:
int
- delete_expired() int [source]#
Delete expired cache keys and return number of entries deleted.
- Returns:
Number of entries deleted.
- Return type:
int
- delete_many(iteratee: str | List[Hashable] | Pattern | Callable) int [source]#
Delete multiple cache keys at once filtered by an iteratee.
The iteratee can be one of:
list
- List of cache keys.str
- Search string that supports Unix shell-style wildcards.re.compile()
- Compiled regular expression.function
- Function that returns whether a key matches. Invoked withiteratee(key)
.
- Parameters:
iteratee – Iteratee to filter by.
- Returns:
Number of cache keys deleted.
- Return type:
int
- evict() int [source]#
Perform cache eviction per the cache replacement policy:
First, remove all expired entries.
Then, remove non-TTL entries using the cache replacement policy.
When removing non-TTL entries, this method will only remove the minimum number of entries to reduce the number of entries below
maxsize
. Ifmaxsize
is0
, then only expired entries will be removed.- Returns:
Number of cache entries evicted.
- expire_times() Dict[Hashable, int | float] [source]#
Return cache expirations for TTL keys.
- Returns:
dict
- expired(key: Hashable, expires_on: int | float | None = None) bool [source]#
Return whether cache key is expired or not.
- Parameters:
key – Cache key.
expires_on – Timestamp of when the key is considered expired. Defaults to
None
which uses the current value returned fromtimer()
.
- get(key: Hashable, default: Any = None) Any [source]#
Return the cache value for key or default or
missing(key)
if it doesn’t exist or has expired.- Parameters:
key – Cache key.
default – Value to return if key doesn’t exist. If any value other than
None
, then it will take precedence overmissing
and be used as the return value. If default is callable, it will function likemissing
and its return value will be set for the cache key. Defaults toNone
.
- Returns:
The cached value.
- get_many(iteratee: str | List[Hashable] | Pattern | Callable) dict [source]#
Return many cache values as a
dict
of key/value pairs filtered by an iteratee.The iteratee can be one of:
list
- List of cache keysstr
- Search string that supports Unix shell-style wildcardsre.compile()
- Compiled regular expressioncallable
- Function that returns whether a key matches. Invoked withiteratee(key)
- Parameters:
iteratee – Iteratee to filter by.
- get_ttl(key: Hashable) int | float | None [source]#
Return the remaining time to live of a key that has a TTL.
- Parameters:
key – Cache key.
- Returns:
The remaining time to live of key or
None
if the key doesn’t exist or has expired.
- items() ItemsView [source]#
Return a
dict_items
view of cache items.Warning
Returned data is copied from the cache object, but any modifications to mutable values will modify this cache object’s data.
- keys() KeysView [source]#
Return
dict_keys
view of all cache keys.Note
Cache is copied from the underlying cache storage before returning.
- memoize(*, ttl: int | float | None = None, typed: bool = False) Callable[[F], F] [source]#
Decorator that wraps a function with a memoizing callable and works on both synchronous and asynchronous functions.
Each return value from the function will be cached using the function arguments as the cache key. The cache object can be accessed at
<function>.cache
. The uncached version (i.e. the original function) can be accessed at<function>.uncached
. Each return value from the function will be cached using the function arguments as the cache key. Calculate the cache key for the provided function arguments for use in other operations of the<function>.cache
object using the function accessible at<function>.cache_key
- popitem() Tuple[Hashable, Any] [source]#
Delete and return next cache item,
(key, value)
, based on cache replacement policy while ignoring expiration times (i.e. the selection of the item to pop is based solely on the cache key ordering).- Returns:
Two-element tuple of deleted cache
(key, value)
.
- set(key: Hashable, value: Any, ttl: int | float | None = None) None [source]#
Set cache key/value and replace any previously set cache key.
If the cache key previously existed, setting it will move it to the end of the cache stack which means it would be evicted last.
- class cacheout.cache.RemovalCause(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#
An enum to represent the cause for the removal of a cache entry.
- DELETE#
indicates that the cache entry was deleted by delete() or delete_many() explicitly.
- EXPIRED#
indicates that the cache entry was removed because it expired.
- FULL#
indicates that the cache entry was removed because cache has been full (reached the maximum size limit).
- POPITEM#
indicates that the cache entry was deleted by popitem().
- cacheout.cache.T_DECORATOR#
Decorator type.
alias of
Callable
[[F
],F
]
- cacheout.cache.T_FILTER#
Possible types that can be used to filter cache keys.
alias of
Union
[str
,List
[Hashable
],Pattern
,Callable
]
- cacheout.cache.T_ON_DELETE_CALLBACK#
Callback that will be executed when a cache entry is removed. It is called with arguments
(key, value, cause)
where key is the cache key, value is the cached value at the time of deletion, and cause is the reason the key was removed (seeRemovalCause
for enumerated causes).alias of
Optional
[Callable
[[Hashable
,Any
,RemovalCause
],None
]]
- cacheout.cache.T_ON_GET_CALLBACK#
Callback that will be executed when a cache entry is retrieved. It is called with arguments
(key, value, exists)
where key is the cache key, value is the value retrieved (could be the default), and exists is whether the cache key exists or not.alias of
Optional
[Callable
[[Hashable
,Any
,bool
],None
]]
- cacheout.cache.T_ON_SET_CALLBACK#
Callback that will be executed when a cache entry is set. It is called with arguments
(key, new_value, old_value)
where key is the cache key, new_value is the value is set, and old_value is the value it replaced (if the key didn’t exist before, it’sUNSET
).alias of
Optional
[Callable
[[Hashable
,Any
,Any
],None
]]
- cacheout.cache.T_TTL#
Possible types for TTL (time to live) value.
alias of
Union
[int
,float
]
- cacheout.cache.UNSET = <object object>#
Sentinel value to indicate that an argument was not set.