boto3_client_cache.cache

Low-level API for caching boto3 clients based on their initialization parameters.

Module Attributes

EvictionPolicy	Type alias for supported cache types
CacheType	Type alias for cacheable objects in boto3-client-cache.

Classes

ClientCache	Core interface for creating client cache instances.
ClientCacheKey	A unique, hashable key for caching clients based on their initialization parameters.
LFUClientCache	A thread-safe LFU cache [1] for storing clients which can be used exactly like a dictionary.
LFUResourceCache	A thread-safe LFU cache [1] for storing resources which can be used exactly like a dictionary.
LRUClientCache	A thread-safe LRU cache for storing clients which can be used exactly like a dictionary.
LRUResourceCache	A thread-safe LRU cache for storing resources which can be used exactly like a dictionary.
ResourceCache	Core interface for creating resource cache instances.
ResourceCacheKey	A unique, hashable key for caching resources based on their initialization parameters.

boto3_client_cache.cache.CacheType

Type alias for cacheable objects in boto3-client-cache.

alias of Literal[‘client’, ‘resource’]

class boto3_client_cache.cache.ClientCache

Core interface for creating client cache instances.

Added in version 0.1.0.

Parameters:

eviction_policyEvictionPolicy, optional

The type of cache to create. Case sensitive. Options are “LRU” and “LFU”. Defaults to “LRU”.

*argsAny, optional

Positional arguments to pass to the cache constructor. Refer to the docs for LRUClientCache and LFUClientCache for supported arguments.

**kwargsAny, optional

Keyword arguments to pass to the cache constructor. Refer to the docs for LRUClientCache and LFUClientCache for supported arguments.

Returns:

LRUClientCache | LFUClientCache

An LRU or LFU client cache instance.

Raises:

ClientCacheError

Raised when an error occurs related to cache operations, such as using an invalid key, eviction policy, or value type.

ClientCacheExistsError

Raised when attempting to add a client which already exists in the cache.

ClientCacheNotFoundError

Raised when attempting to retrieve or delete a client which does not exist in the cache.

See also

boto3_client_cache.cache.LFUClientCache

boto3_client_cache.cache.LRUClientCache

Examples

LRU cache example:

>>> from boto3_client_cache import ClientCache, ClientCacheKey
>>> cache = ClientCache(max_size=2)
>>> kwargs = {"service_name": "s3", "region_name": "us-west-2"}
>>> cache[ClientCacheKey(**kwargs)] = boto3.client(**kwargs)

LFU cache example:

>>> from boto3_client_cache import ClientCache, ClientCacheKey
>>> cache = ClientCache("LFU", max_size=2)
>>> kwargs = {"service_name": "s3", "region_name": "us-west-2"}
>>> cache[ClientCacheKey(**kwargs)] = boto3.client(**kwargs)

class boto3_client_cache.cache.ClientCacheKey

A unique, hashable key for caching clients based on their initialization parameters.

In order to interact with the cache, instances of this class should be created using the same arguments that would be used to initialize the boto3 client.

Added in version 0.1.0.

Parameters:

*argsAny, optional

Positional arguments used to create the cache key.

**kwargsAny, optional

Keyword arguments used to create the cache key.

Attributes

key	(tuple) The unique key representing the client’s initialization parameters.
label	(str) A human-readable label for the cache key, useful for debugging.

Examples

Creating a cache key for an S3 client initialized with a specific region:

>>> from boto3_client_cache import ClientCacheKey
...
>>> key = ClientCacheKey("s3", region_name="us-west-2")

boto3_client_cache.cache.EvictionPolicy

Type alias for supported cache types

alias of Literal[‘LRU’, ‘LFU’]

class boto3_client_cache.cache.LFUClientCache

A thread-safe LFU cache [1] for storing clients which can be used exactly like a dictionary.

The cache has a maximum size attribute, and retrieved clients are promoted to a higher frequency bucket. When the cache exceeds its maximum size, the least frequently used client is evicted. If multiple clients share the same frequency, the least recently used client within that frequency bucket is evicted first. When setting a client, use ClientCacheKey for the key, not *args and **kwargs.

Editing the max size of the cache after initialization is supported, and will evict least frequently used items until the cache size is within the new limit if the new maximum size is less than the current number of items in the cache.

Attempting to overwrite an existing client in the cache will raise an error.

LFUClientCache does not support fromkeys, update, setdefault, the |= operator, or the | operator.

Added in version 1.0.0.

Parameters:

max_sizeint, optional

The maximum number of clients to store in the cache. Defaults to 10.

Attributes

max_size

The maximum number of clients to store in the cache.

Methods

clear() -> None	Clears all clients from the cache.
copy() -> LFUClientCache	Returns a shallow copy of the cache.
get(key: ClientCacheKey, default: BaseClient = None) -> BaseClient | None	Gets the client associated with the given key, or returns the default.
items() -> Tuple[Tuple[ClientCacheKey, BaseClient], …]	Returns the items in the cache as (key, client) tuples.
keys() -> Tuple[ClientCacheKey, …]	Returns the keys in the cache.
pop(key: ClientCacheKey) -> BaseClient	Pops and returns the client associated with the given key.
popitem() -> Tuple[ClientCacheKey, BaseClient]	Pops and returns the least frequently used client as a (key, client) tuple.
values() -> Tuple[BaseClient, …]	Returns the clients in the cache.

Raises:

ClientCacheError

Raised when an error occurs related to cache operations, such as using an invalid key or value type.

ClientCacheExistsError

Raised when attempting to add a client which already exists in the cache.

ClientCacheNotFoundError

Raised when attempting to retrieve or delete a client which does not exist in the cache.

References

[1] (1,2)

“An O(1) algorithm for implementing the LFU cache eviction scheme”, http://dhruvbird.com/lfu.pdf

Examples

>>> from boto3_client_cache import LFUClientCache, ClientCacheKey
>>> cache = LFUClientCache(max_size=2)
>>> kwargs = {"service_name": "s3", "region_name": "us-west-2"}
>>> cache[ClientCacheKey(**kwargs)] = boto3.client(**kwargs)

clear() → None

Clears all items from the cache.

copy() → _BaseLFUCache

Returns a shallow copy of the cache.

get(key: _CacheKeyType, default: _CacheObjType | None = None) → _CacheObjType | None

Gets the object using the given key, or returns the default.

items() → Tuple[Tuple[_CacheKeyType, _CacheObjType], ...]

Returns the items in LFU order.

keys() → Tuple[_CacheKeyType, ...]

Returns the keys in LFU order.

Keys are ordered by increasing frequency. Within each frequency bucket, keys are ordered least-recently used to most-recently used.

property max_size: int

The maximum number of clients to store in the cache.

pop(key: _CacheKeyType) → _CacheObjType

Pops and returns the object associated with the given key.

popitem() → Tuple[_CacheKeyType, _CacheObjType]

Pops and returns the LFU item from the cache.

values() → Tuple[_CacheObjType, ...]

Returns the values in LFU order.

class boto3_client_cache.cache.LFUResourceCache

A thread-safe LFU cache [1] for storing resources which can be used exactly like a dictionary.

The cache has a maximum size attribute, and retrieved resources are promoted to a higher frequency bucket. When the cache exceeds its maximum size, the least frequently used resource is evicted. If multiple resources share the same frequency, the least recently used resource within that frequency bucket is evicted first. When setting a resource, use ResourceCacheKey for the key, not *args and **kwargs.

Editing the max size of the cache after initialization is supported, and will evict least frequently used items until the cache size is within the new limit if the new maximum size is less than the current number of items in the cache.

Attempting to overwrite an existing resource in the cache will raise an error.

LFUResourceCache does not support fromkeys, update, setdefault, the |= operator, or the | operator.

Added in version 2.0.0.

Parameters:

max_sizeint, optional

The maximum number of resources to store in the cache. Defaults to 10.

Attributes

max_size

The maximum number of clients to store in the cache.

Methods

clear() -> None	Clears all resources from the cache.
copy() -> LFUResourceCache	Returns a shallow copy of the cache.
get(	key: ResourceCacheKey, default: ServiceResource = None
) -> ServiceResource | None	Gets the resource associated with the given key, or returns the default.
items() -> Tuple[Tuple[ResourceCacheKey, ServiceResource], …]	Returns the items in the cache as (key, resource) tuples.
keys() -> Tuple[ResourceCacheKey, …]	Returns the keys in the cache.
pop(key: ResourceCacheKey) -> ServiceResource	Pops and returns the resource associated with the given key.
popitem() -> Tuple[ResourceCacheKey, ServiceResource]	Pops and returns the least frequently used resource as a (key, resource) tuple.
values() -> Tuple[ServiceResource, …]	Returns the resources in the cache.

Raises:

ResourceCacheError

Raised when an error occurs related to cache operations, such as using an invalid key or value type.

ResourceCacheExistsError

Raised when attempting to add a resource which already exists in the cache.

ResourceCacheNotFoundError

Raised when attempting to retrieve or delete a resource which does not exist in the cache.

References

[1] (1,2)

“An O(1) algorithm for implementing the LFU cache eviction scheme”, http://dhruvbird.com/lfu.pdf

Examples

>>> from boto3_client_cache import LFUResourceCache, ResourceCacheKey
>>> cache = LFUResourceCache(max_size=2)
>>> kwargs = {"service_name": "s3", "region_name": "us-west-2"}
>>> cache[ResourceCacheKey(**kwargs)] = boto3.resource(**kwargs)

clear() → None

Clears all items from the cache.

copy() → _BaseLFUCache

Returns a shallow copy of the cache.

get(key: _CacheKeyType, default: _CacheObjType | None = None) → _CacheObjType | None

Gets the object using the given key, or returns the default.

items() → Tuple[Tuple[_CacheKeyType, _CacheObjType], ...]

Returns the items in LFU order.

keys() → Tuple[_CacheKeyType, ...]

Returns the keys in LFU order.

Keys are ordered by increasing frequency. Within each frequency bucket, keys are ordered least-recently used to most-recently used.

property max_size: int

The maximum number of clients to store in the cache.

pop(key: _CacheKeyType) → _CacheObjType

Pops and returns the object associated with the given key.

popitem() → Tuple[_CacheKeyType, _CacheObjType]

Pops and returns the LFU item from the cache.

values() → Tuple[_CacheObjType, ...]

Returns the values in LFU order.

class boto3_client_cache.cache.LRUClientCache

A thread-safe LRU cache for storing clients which can be used exactly like a dictionary.

The cache has a maximum size attribute, and retrieved and newly added clients are marked as recently used. When the cache exceeds its maximum size, the least recently used client is evicted. When setting a client, use ClientCacheKey for the key, not *args and **kwargs.

Editing the max size of the cache after initialization is supported, and will evict least recently used items until the cache size is within the new limit if the new maximum size is less than the current number of items in the cache.

Attempting to overwrite an existing client in the cache will raise an error.

LRUClientCache does not support fromkeys, update, setdefault, the |= operator, or the | operator.

Added in version 0.1.0.

Parameters:

max_sizeint, optional

The maximum number of clients to store in the cache. Defaults to 10.

Attributes

max_size

The maximum number of clients to store in the cache.

Methods

clear() -> None	Clears all clients from the cache.
copy() -> LRUClientCache	Returns a shallow copy of the cache.
get(key: ClientCacheKey, default: BaseClient = None) -> BaseClient | None	Gets the client associated with the given key, or returns the default.
items() -> Tuple[Tuple[ClientCacheKey, BaseClient], …]	Returns the items in the cache as (key, client) tuples.
keys() -> Tuple[ClientCacheKey, …]	Returns the keys in the cache.
pop(key: ClientCacheKey) -> BaseClient	Pops and returns the client associated with the given key.
popitem() -> Tuple[ClientCacheKey, BaseClient]	Pops and returns the least recently used client as a (key, client) tuple.
values() -> Tuple[BaseClient, …]	Returns the clients in the cache.

Raises:

ClientCacheError

Raised when an error occurs related to cache operations, such as using an invalid key or value type.

ClientCacheExistsError

Raised when attempting to add a client which already exists in the cache.

ClientCacheNotFoundError

Raised when attempting to retrieve or delete a client which does not exist in the cache.

Examples

>>> from boto3_client_cache import LRUClientCache, ClientCacheKey
>>> cache = LRUClientCache(max_size=2)
>>> kwargs = {"service_name": "s3", "region_name": "us-west-2"}
>>> cache[ClientCacheKey(**kwargs)] = boto3.client(**kwargs)

clear() → None

Clears all items from the cache.

copy() → _BaseLRUCache[_CacheObjType, _CacheKeyType]

Returns a shallow copy of the cache.

get(key: _CacheKeyType, default: _CacheObjType | None = None) → _CacheObjType | None

Gets the object using the given key, or returns the default.

items() → Tuple[Tuple[_CacheKeyType, _CacheObjType], ...]

Returns the items in the cache as (_CacheKeyType, _CacheObjType) tuples.

keys() → Tuple[_CacheKeyType, ...]

Returns the keys in the cache.

property max_size: int

The maximum number of clients to store in the cache.

pop(key: _CacheKeyType) → _CacheObjType

Pops and returns the object associated with the given key.

popitem() → Tuple[_CacheKeyType, _CacheObjType]

Pops and returns the least recently used item from the cache.

values() → Tuple[_CacheObjType, ...]

Returns the values from the cache.

class boto3_client_cache.cache.LRUResourceCache

A thread-safe LRU cache for storing resources which can be used exactly like a dictionary.

The cache has a maximum size attribute, and retrieved and newly added resources are marked as recently used. When the cache exceeds its maximum size, the least recently used resource is evicted. When setting a resource, use ResourceCacheKey for the key, not *args and **kwargs.

Editing the max size of the cache after initialization is supported, and will evict least recently used items until the cache size is within the new limit if the new maximum size is less than the current number of items in the cache.

Attempting to overwrite an existing resource in the cache will raise an error.

LRUResourceCache does not support fromkeys, update, setdefault, the |= operator, or the | operator.

Added in version 2.0.0.

Parameters:

max_sizeint, optional

The maximum number of resources to store in the cache. Defaults to 10.

Attributes

max_size

The maximum number of clients to store in the cache.

Methods

clear() -> None	Clears all resources from the cache.
copy() -> LRUResourceCache	Returns a shallow copy of the cache.
get(	key: ResourceCacheKey, default: ServiceResource = None
) -> ServiceResource | None	Gets the resource associated with the given key, or returns the default.
items() -> Tuple[Tuple[ResourceCacheKey, ServiceResource], …]	Returns the items in the cache as (key, resource) tuples.
keys() -> Tuple[ResourceCacheKey, …]	Returns the keys in the cache.
pop(key: ResourceCacheKey) -> ServiceResource	Pops and returns the resource associated with the given key.
popitem() -> Tuple[ResourceCacheKey, ServiceResource]	Pops and returns the least recently used resource as a (key, resource) tuple.
values() -> Tuple[ServiceResource, …]	Returns the resources in the cache.

Raises:

ResourceCacheError

Raised when an error occurs related to cache operations, such as using an invalid key or value type.

ResourceCacheExistsError

Raised when attempting to add a resource which already exists in the cache.

ResourceCacheNotFoundError

Raised when attempting to retrieve or delete a resource which does not exist in the cache.

Examples

>>> from boto3_client_cache import LRUResourceCache, ResourceCacheKey
>>> cache = LRUResourceCache(max_size=2)
>>> kwargs = {"service_name": "s3", "region_name": "us-west-2"}
>>> cache[ResourceCacheKey(**kwargs)] = boto3.client(**kwargs)

clear() → None

Clears all items from the cache.

copy() → _BaseLRUCache[_CacheObjType, _CacheKeyType]

Returns a shallow copy of the cache.

get(key: _CacheKeyType, default: _CacheObjType | None = None) → _CacheObjType | None

Gets the object using the given key, or returns the default.

items() → Tuple[Tuple[_CacheKeyType, _CacheObjType], ...]

Returns the items in the cache as (_CacheKeyType, _CacheObjType) tuples.

keys() → Tuple[_CacheKeyType, ...]

Returns the keys in the cache.

property max_size: int

The maximum number of clients to store in the cache.

pop(key: _CacheKeyType) → _CacheObjType

Pops and returns the object associated with the given key.

popitem() → Tuple[_CacheKeyType, _CacheObjType]

Pops and returns the least recently used item from the cache.

values() → Tuple[_CacheObjType, ...]

Returns the values from the cache.

class boto3_client_cache.cache.ResourceCache

Core interface for creating resource cache instances.

Added in version 2.0.0.

Parameters:

eviction_policyEvictionPolicy, optional

The type of cache to create. Case sensitive. Options are “LRU” and “LFU”. Defaults to “LRU”.

*argsAny, optional

Positional arguments to pass to the cache constructor. Refer to the docs for LRUResourceCache and LFUResourceCache for supported arguments.

**kwargsAny, optional

Keyword arguments to pass to the cache constructor. Refer to the docs for LRUResourceCache and LFUResourceCache for supported arguments.

Returns:

LRUResourceCache | LFUResourceCache

An LRU or LFU resource cache instance.

Raises:

ResourceCacheError

Raised when an error occurs related to cache operations, such as using an invalid key, eviction policy, or value type.

ResourceCacheExistsError

Raised when attempting to add a resource which already exists in the cache.

ResourceCacheNotFoundError

Raised when attempting to retrieve or delete a resource which does not exist in the cache.

See also

boto3_client_cache.cache.LFUResourceCache

boto3_client_cache.cache.LRUResourceCache

Examples

LRU cache example:

>>> from boto3_client_cache import ResourceCache, ResourceCacheKey
>>> cache = ResourceCache(max_size=2)
>>> kwargs = {"service_name": "s3", "region_name": "us-west-2"}
>>> cache[ResourceCacheKey(**kwargs)] = boto3.resource(**kwargs)

LFU cache example:

>>> from boto3_client_cache import ResourceCache, ResourceCacheKey
>>> cache = ResourceCache("LFU", max_size=2)
>>> kwargs = {"service_name": "s3", "region_name": "us-west-2"}
>>> cache[ResourceCacheKey(**kwargs)] = boto3.resource(**kwargs)

class boto3_client_cache.cache.ResourceCacheKey

A unique, hashable key for caching resources based on their initialization parameters.

In order to interact with the cache, instances of this class should be created using the same arguments that would be used to initialize the boto3 resource.

Added in version 2.0.0.

Parameters:

*argsAny, optional

Positional arguments used to create the cache key.

**kwargsAny, optional

Keyword arguments used to create the cache key.

Attributes

key	(tuple) The unique key representing the resource’s initialization parameters.
label	(str) A human-readable label for the cache key, useful for debugging.

Examples

Creating a cache key for an S3 resource initialized with a specific region:

>>> from boto3_client_cache import ResourceCacheKey
...
>>> key = ResourceCacheKey("s3", region_name="us-west-2")