boto3-client-cache 0.1.1

A simple Python package with a cache for boto3 clients.

boto3-client-cache

Description

A simple Python package which caches boto3 clients.

Includes LRU eviction. LFU eviction will be included in a future release.

Raison d'Être

boto3 clients consume a large amount of memory. Many developers never notice. At scale, however, this becomes painfully obvious. There is a clear incentive, therefore, to avoid initializing duplicate client objects. Client caching is an obvious solution.

The most challenging aspect of boto3 client caching is selecting robust and standardized unique keys. Managing ad-hoc keys at scale is unwieldy and insecure. boto3-client-cache hashes according to 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 CacheKey object in order to set or retrieve a client.

From a developer experience perspective, this design - that is, forcing CacheKey - may feel clunky; however, it ensures setting and retrieving clients are unambiguous operations. Further, locking the client cache, as boto3-client-cache does, prevents race conditions, enabling developers to confidently employ the client cache at scale.

Although boto3-client-cache can help any developer working with the AWS Python SDK at any scale, it was designed primarily for security, cloud, machine learning, and platform teams operating at scale.

boto3-client-cache, it should be noted, is also a critical dependency for boto3-refresh-session.

Installation

pip install boto3-client-cache

Quickstart

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)

# make the assignment
cache[key] = boto3.client(**kwargs)

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

# this raises a ClientCacheExistsError
cache[key] = boto3.client(**kwargs)

# this raises a ClientCacheNotFoundError
cache[ClientCacheKey(service_name="ec2", region_name="us-west-2")]

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

# this raises a ClientCacheError
cache["this is not a ClientCacheKey"]

# and this raises a ClientCacheError
cache[ClientCacheKey("s3")] = "this is not a boto3 client"

License

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

Special Thanks

• Patrick Sanders