boto3-client-cache 1.0.0

boto3-client-cache provides a concurrency-safe, bounded cache for boto3 clients with deterministic identity semantics.

boto3-client-cache

Description

boto3-client-cache provides a concurrency-safe, bounded cache for boto3 clients with deterministic identity semantics.

LRU and LFU eviction are supported.

Why this Exists

boto3 clients consume a large amount of memory. Many developers never notice this. At scale, however, the memory footprint of boto3 clients often becomes clear through manifold consequences. Client caching is an obvious choice for managing multiple clients at scale. There are, to my knowledge, no other open-source tools available which do what boto3-client-cache does.

Design

The most important but challenging design choice for client caching is selecting and enforcing a robust and standardized methodology for unique keys. boto3-client-cache hashes according to boto3 client signatures.

Setting and retrieving clients from the client cache therefore requires an explicit declaration of intention -- that is, the developer must explicitly pass client initialization parameters to a ClientCacheKey object in order to set or retrieve boto3 clients. This ensures setting and retrieving clients are unambiguous and deterministic operations. By locking the client cache, as boto3-client-cache does, race conditions are prevented, enabling developers to confidently employ the client cache at scale with predictable cache eviction behavior. Lastly, by designing the cache like a dict in the standard Python library, the cache is ergonomically familiar and thus easy to use.

These decisions reflect the core design goals of boto3-client-cache: safety at scale, deterministic behavior, ergonomic interfacing, and explicit identity.

Installation

pip install boto3-client-cache

Quickstart

Refer to the official documentation for additional information.

from boto3_client_cache import ClientCache, ClientCacheKey
import boto3

# create an LRU client cache with a maximum size of 30
cache = ClientCache(max_size=30)

# store boto3 client params in an object
kwargs = {"service_name": "s3", "region_name": "us-west-2"}

# create a cache key using those params
key = ClientCacheKey(**kwargs)

# assign a client
cache[key] = boto3.client(**kwargs)

# and retrieve that client using the key
s3_client = cache[key]

Error Semantics

Refer to the official documentation for additional information.

# raises ClientCacheExistsError b/c client(**kwargs) already exists
cache[key] = boto3.client(**kwargs)

# raises ClientCacheNotFoundError b/c the specific client was not cached
cache[ClientCacheKey(service_name="ec2", region_name="us-west-2")]

# returns None instead of raising ClientCacheNotFoundError
cache.get(ClientCacheKey(service_name="ec2", region_name="us-west-2"))

# raises ClientCacheError b/c the key is not a ClientCacheKey
cache["this is not a ClientCacheKey"]

# raises ClientCacheError b/c the object is not a client
cache[ClientCacheKey("s3")] = "this is not a boto3 client"

License

boto3-client-cache is licensed by the Apache Software License (2.0).

Contributing

Refer to the contributing guidelines for additional information on how to contribute to boto3-client-cache.

Special Thanks

• Patrick Sanders