Metadata-Version: 2.4
Name: boto3-client-cache
Version: 0.1.0
Summary: A simple Python package with a cache for boto3 clients.
Project-URL: Homepage, https://michaelthomasletts.com/boto3-client-cache
Project-URL: Repository, https://github.com/michaelthomasletts/boto3-client-cache
Project-URL: Documentation, https://michaelthomasletts.com/boto3-client-cache
Author-email: Mike Letts <lettsmt@gmail.com>
Maintainer-email: Mike Letts <lettsmt@gmail.com>
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: botocore
Description-Content-Type: text/markdown

# 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-client-cache](https://github.com/michaelthomasletts/boto3-client-cache).

## Installation

```bash
pip install boto3-client-cache
```

## Quickstart

```python
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)](https://github.com/michaelthomasletts/boto3-client-cache/blob/main/LICENSE).

## Special Thanks

- [Patrick Sanders](https://github.com/patricksanders)