Caching

coredis.cache

Built in caches

class TrackingCache(max_keys: int = 2**12, max_size_bytes: int = 64 * 1024 * 1024, max_idle_seconds: int = 5, confidence: float = 100.0, dynamic_confidence: bool = False, cache: LRUCache[LRUCache[LRUCache[ResponseType]]] | None = None, stats: CacheStats | None = None)

An LRU cache that uses server assisted client caching to ensure local cache entries are invalidated if any operations are performed on the keys by another client.

This class proxies to either NodeTrackingCache or ClusterTrackingCache depending on which type of client it is passed into.

Parameters:

• max_keys – maximum keys to cache. A negative value represents and unbounded cache.

• max_size_bytes – maximum size in bytes for the local cache. A negative value represents an unbounded cache.

• max_idle_seconds – maximum duration to tolerate no updates from the server. When the duration is exceeded the connection and cache will be reset.

• confidence – 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

• dynamic_confidence – Whether to adjust the confidence based on sampled validations. Tainted values drop the confidence by 0.1% and confirmations of correct cached values will increase the confidence by 0.01% upto 100.

async initialize(client: 'coredis.client.Redis[Any]' | 'coredis.client.RedisCluster[Any]') → TrackingCache

Associate and initialize this cache with the provided client

property healthy: bool

Whether the cache is healthy and should be taken seriously

property confidence: float

Confidence in cached values between 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

property stats: CacheStats

Returns the current stats for the cache

get_client_id(connection: BaseConnection) → int | None

If the cache supports receiving invalidation events from the server return the client_id that the connection should send redirects to.

get(command: bytes, key: bytes, *args: ValueT) → ResponseType

Fetch the cached response for command/key/args combination

put(command: bytes, key: bytes, *args: ValueT, value: ResponseType) → None

Cache the response for command/key/args combination

invalidate(*keys: ValueT) → None

Invalidate any cached entries for the provided keys

feedback(command: bytes, key: bytes, *args: ValueT, match: bool) → None

Provide feedback about a key as having either a match or drift from the actual server side value

reset() → None

Reset the cache

shutdown() → None

Explicitly shutdown the cache

share() → TrackingCache

Create a copy of this cache that can be used to share memory with another client.

In the example below c1 and c2 have their own instances of TrackingCache but share the same in-memory local cached responses:

c1 = await coredis.Redis(cache=TrackingCache())
c2 = await coredis.Redis(cache=c1.cache.share())

class NodeTrackingCache(max_keys: int = 2**12, max_size_bytes: int = 64 * 1024 * 1024, max_idle_seconds: int = 5, confidence: float = 100, dynamic_confidence: bool = False, cache: LRUCache[LRUCache[LRUCache[ResponseType]]] | None = None, stats: CacheStats | None = None)

An LRU cache that uses server assisted client caching to ensure local cache entries are invalidated if any operations are performed on the keys by another client.

Parameters:

• max_keys – maximum keys to cache. A negative value represents and unbounded cache.

• max_size_bytes – maximum size in bytes for the local cache. A negative value represents an unbounded cache.

• max_idle_seconds – maximum duration to tolerate no updates from the server. When the duration is exceeded the connection and cache will be reset.

• confidence – 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

• dynamic_confidence – Whether to adjust the confidence based on sampled validations. Tainted values drop the confidence by 0.1% and confirmations of correct cached values will increase the confidence by 0.01% upto 100.

property healthy: bool

Whether the cache is healthy and should be taken seriously

property confidence: float

Confidence in cached values between 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

property stats: CacheStats

Returns the current stats for the cache

get(command: bytes, key: bytes, *args: ValueT) → ResponseType

Fetch the cached response for command/key/args combination

put(command: bytes, key: bytes, *args: ValueT, value: ResponseType) → None

Cache the response for command/key/args combination

invalidate(*keys: ValueT) → None

Invalidate any cached entries for the provided keys

feedback(command: bytes, key: bytes, *args: ValueT, match: bool) → None

Provide feedback about a key as having either a match or drift from the actual server side value

reset() → None

Reset the cache

async initialize(client: 'coredis.client.Redis[Any]' | 'coredis.client.RedisCluster[Any]') → NodeTrackingCache

Associate and initialize this cache with the provided client

shutdown() → None

Explicitly shutdown the cache

get_client_id(client: BaseConnection) → int | None

If the cache supports receiving invalidation events from the server return the client_id that the connection should send redirects to.

class ClusterTrackingCache(max_keys: int = 2**12, max_size_bytes: int = 64 * 1024 * 1024, max_idle_seconds: int = 5, confidence: float = 100, dynamic_confidence: bool = False, cache: LRUCache[LRUCache[LRUCache[ResponseType]]] | None = None, stats: CacheStats | None = None)

An LRU cache for redis cluster that uses server assisted client caching to ensure local cache entries are invalidated if any operations are performed on the keys by another client.

The cache maintains an additional connection per node (including replicas) in the cluster to listen to invalidation events

Parameters:

• max_keys – maximum keys to cache. A negative value represents and unbounded cache.

• max_size_bytes – maximum size in bytes for the local cache. A negative value represents an unbounded cache.

• max_idle_seconds – maximum duration to tolerate no updates from the server. When the duration is exceeded the connection and cache will be reset.

• confidence – 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

• dynamic_confidence – Whether to adjust the confidence based on sampled validations. Tainted values drop the confidence by 0.1% and confirmations of correct cached values will increase the confidence by 0.01% upto 100.

async initialize(client: 'coredis.client.Redis[Any]' | 'coredis.client.RedisCluster[Any]') → ClusterTrackingCache

Associate and initialize this cache with the provided client

property healthy: bool

Whether the cache is healthy and should be taken seriously

property confidence: float

Confidence in cached values between 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

property stats: CacheStats

Returns the current stats for the cache

get_client_id(connection: BaseConnection) → int | None

If the cache supports receiving invalidation events from the server return the client_id that the connection should send redirects to.

get(command: bytes, key: bytes, *args: ValueT) → ResponseType

Fetch the cached response for command/key/args combination

put(command: bytes, key: bytes, *args: ValueT, value: ResponseType) → None

Cache the response for command/key/args combination

invalidate(*keys: ValueT) → None

Invalidate any cached entries for the provided keys

feedback(command: bytes, key: bytes, *args: ValueT, match: bool) → None

Provide feedback about a key as having either a match or drift from the actual server side value

reset() → None

Reset the cache

shutdown() → None

Explicitly shutdown the cache

Implementing a custom cache

All caches accepted by Redis or RedisCluster must implement AbstractCache

class AbstractCache

Abstract class representing a local cache that can be used by coredis.Redis or coredis.RedisCluster

abstract async initialize(client: 'coredis.client.Redis[Any]' | 'coredis.client.RedisCluster[Any]') → AbstractCache

Associate and initialize this cache with the provided client

abstract property healthy: bool

Whether the cache is healthy and should be taken seriously

abstract get(command: bytes, key: bytes, *args: ValueT) → ResponseType

Fetch the cached response for command/key/args combination

abstract put(command: bytes, key: bytes, *args: ValueT, value: ResponseType) → None

Cache the response for command/key/args combination

abstract invalidate(*keys: ValueT) → None

Invalidate any cached entries for the provided keys

abstract reset() → None

Reset the cache

abstract shutdown() → None

Explicitly shutdown the cache

Additionally, caches can opt in to additional features by implementing any of the following protocols:

class SupportsClientTracking(*args, **kwargs)

If a cache implements SupportsClientTracking, the Redis and RedisCluster clients will ensure that the client returned by get_client_id() is set using the client_tracking() command on any connection returned by the clients.

abstract get_client_id(connection: BaseConnection) → int | None

If the cache supports receiving invalidation events from the server return the client_id that the connection should send redirects to.

class SupportsStats(*args, **kwargs)

Protocol of a cache that provides cache statistics

abstract property stats: CacheStats

Returns the current stats for the cache

class SupportsSampling(*args, **kwargs)

If a cache implements SupportsSampling, methods that support caching will sample the response from the cache and test it against an uncached response from the server based on the confidence returned by confidence. The outcome of the validation will be fed back to the cache using feedback() and in the case that there was no match, the uncached response will be returned.

abstract property confidence: float

Confidence in cached values between 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

abstract feedback(command: bytes, key: bytes, *args: ValueT, match: bool) → None

Provide feedback about a key as having either a match or drift from the actual server side value

class CacheStats(hits: ~collections.Counter[bytes] = <factory>, misses: ~collections.Counter[bytes] = <factory>, invalidations: ~collections.Counter[bytes] = <factory>, dirty: ~collections.Counter[bytes] = <factory>)

Summary of statics to be used by instances of coredis.cache.AbstractCache The individual counters exposed are not guaranteed to retain fine grained per key metrics but the totals (returned by coredis.cache.CacheStats.summary) will be maintained aggregated.

hits: Counter[bytes]

summary of hits by key (for all commands)

misses: Counter[bytes]

summary of misses by key (for all commands)

invalidations: Counter[bytes]

number of invalidations including server side and local invalidations

dirty: Counter[bytes]

counter of keys which returned dirty results based on confidence testing

property summary: dict[str, int]

Aggregated totals of hits, misses, dirty_hits and invalidations