Cache

The cache module provides the Cache class which is used as the base for all other cache types.

class cacheout.cache.Cache(maxsize=None, ttl=None, timer=None, default=None)[source]

An in-memory, FIFO cache object that 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 the OrderedDict 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.

Type:int, optional
ttl

Default TTL for all cache entries. Defaults to 0 which means that entries do not expire.

Type:int, optional
timer

Timer function to use to calculate TTL expiration. Defaults to time.time.

Type:callable, optional
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.

Type:mixed, optional
add(key, value, ttl=None)[source]

Add cache key/value if it doesn’t already exist. Essentially, this method ignores keys that exist which leaves the original TTL in tact.

Note

Cache key must be hashable.

Parameters:
  • key (mixed) – Cache key to add.
  • value (mixed) – Cache value.
  • ttl (int, optional) – TTL value. Defaults to None which uses ttl.
add_many(items, ttl=None)[source]

Add multiple cache keys at once.

Parameters:items (dict) – Mapping of cache key/values to set.
clear()[source]

Clear all cache entries.

configure(maxsize=None, ttl=None, timer=None, default=None)[source]

Configure cache settings.

This method is meant to support runtime level configurations for global level cache objects.

copy()[source]

Return a copy of the cache.

Returns:OrderedDict
delete(key)[source]

Delete cache key and return number of entries deleted (1 or 0).

Returns:1 if key was deleted, 0 if key didn’t exist.
Return type:int
delete_expired()[source]

Delete expired cache keys and return number of entries deleted.

Returns:Number of entries deleted.
Return type:int
delete_many(iteratee)[source]

Delete multiple cache keys at once filtered by an iteratee that 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 with iteratee(key).
Parameters:iteratee (list|str|Pattern|callable) – Iteratee to filter by.
Returns:Number of cache keys deleted.
Return type:int
evict()[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. If maxsize is 0, then only expired entries will be removed.

Returns:Number of cache entries evicted.
Return type:int
expire_times()[source]

Return cache expirations for TTL keys.

Returns:dict
expired(key, expires_on=None)[source]

Return whether cache key is expired or not.

Parameters:
  • key (mixed) – Cache key.
  • expires_on (float, optional) – Timestamp of when the key is considered expired. Defaults to None which uses the current value returned from timer().
Returns:

bool

full()[source]

Return whether the cache is full or not.

Returns:bool
get(key, default=None)[source]

Return the cache value for key or default or missing(key) if it doesn’t exist or has expired.

Parameters:
  • key (mixed) – Cache key.
  • default (mixed, optional) – Value to return if key doesn’t exist. If any value other than None, then it will take precendence over missing and be used as the return value. If default is callable, it will function like missing and its return value will be set for the cache key. Defaults to None.
Returns:

The cached value.

Return type:

mixed

get_many(iteratee, default=None)[source]

Return many cache values as a dict of key/value pairs filtered by an iteratee that 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 with iteratee(key).
Parameters:
  • iteratee (list|str|Pattern|callable) – Iteratee to filter by.
  • default (mixed, optional) – Value to return if key doesn’t exist. Defaults to None.
Returns:

dict

has(key)[source]

Return whether cache key exists and hasn’t expired.

Returns:bool
items()[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.

Returns:dict_items
keys()[source]

Return dict_keys view of all cache keys.

Note

Cache is copied from the underlying cache storage before returning.

Returns:dict_keys
memoize(*, ttl=None, typed=False)[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.

Keyword Arguments:
 
  • ttl (int, optional) – TTL value. Defaults to None which uses ttl.
  • typed (bool, optional) – Whether to cache arguments of a different type separately. For example, <function>(1) and <function>(1.0) would be treated differently. Defaults to False.
popitem()[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 soley on the cache key ordering).

Returns:Two-element tuple of deleted cache (key, value).
Return type:tuple
set(key, value, ttl=None)[source]

Set cache key/value and replace any previously set cache key. If the cache key previous existed, setting it will move it to the end of the cache stack which means it would be evicted last.

Note

Cache key must be hashable.

Parameters:
  • key (mixed) – Cache key to set.
  • value (mixed) – Cache value.
  • ttl (int, optional) – TTL value. Defaults to None which uses ttl.
set_many(items, ttl=None)[source]

Set multiple cache keys at once.

Parameters:items (dict) – Mapping of cache key/values to set.
size()[source]

Return number of cache entries.

values()[source]

Return dict_values view of all cache values.

Note

Cache is copied from the underlying cache storage before returning.

Returns:dict_values