From b1f16262887c680f0be7c43a9c9f3aa4f3bf69e8 Mon Sep 17 00:00:00 2001 From: Mike Letts <47342651+michaelthomasletts@users.noreply.github.com> Date: Fri, 24 Jul 2026 18:03:34 -0400 Subject: [PATCH 1/5] docs: Error semantics docs updates --- README.md | 8 +++++--- docs/index.rst | 2 +- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3a1f5fa..35b4a83 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ boto3 does not cache client or resource objects natively. There are also, to my The most important but challenging design choice for client and resource caching is selecting and enforcing a robust and standardized methodology for unique keys. **boto3-client-cache hashes according to boto3 client and resource signatures**. -Setting and retrieving clients and resources from the client cache therefore requires an explicit declaration of intention -- that is, *the developer must explicitly pass client and resource initialization parameters to a `ClientCacheKey` or `ResourceCacheKey` object in order to set or retrieve boto3 clients*. This ensures setting and retrieving clients and resources are *unambiguous and deterministic* operations. By locking the cache, as boto3-client-cache does, race conditions are prevented, enabling developers to confidently employ the 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. +Setting and retrieving clients and resources from the client cache therefore requires an explicit declaration of intention — that is, *the developer must explicitly pass client and resource initialization parameters to a `ClientCacheKey` or `ResourceCacheKey` object in order to set or retrieve boto3 clients*. This ensures setting and retrieving clients and resources are *unambiguous and deterministic* operations. By locking the cache, as boto3-client-cache does, race conditions are prevented, enabling developers to confidently employ the 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**. @@ -158,10 +158,12 @@ s3_client = cache[key] Errors for resources are identical to errors for clients, except that the word "Client" is replaced with "Resource" in the exception name. ```python -# raises ClientCacheExistsError b/c client(**kwargs) already exists +# raises ClientCacheExistsError b/c client(**kwargs) already exists +# from the pseudo-code above cache[key] = boto3.client(**kwargs) -# raises ClientCacheNotFoundError b/c the specific client was not cached +# raises ClientCacheNotFoundError b/c the specific client was not +# cached above cache[ClientCacheKey(service_name="ec2", region_name="us-west-2")] # returns None instead of raising ClientCacheNotFoundError diff --git a/docs/index.rst b/docs/index.rst index ad7398e..dfa6780 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,7 +33,7 @@ Design The most important but challenging design choice for client and resource caching is selecting and enforcing a robust and standardized methodology for unique keys. **boto3-client-cache hashes according to boto3 client and resource signatures**. -Setting and retrieving clients and resources from the cache therefore requires an explicit declaration of intention -- that is, *the developer must explicitly pass client or resource initialization parameters to a ClientCacheKey or ResourceCacheKey object in order to set or retrieve boto3 clients or resources*. +Setting and retrieving clients and resources from the cache therefore requires an explicit declaration of intention — that is, *the developer must explicitly pass client or resource initialization parameters to a ClientCacheKey or ResourceCacheKey object in order to set or retrieve boto3 clients or resources*. This ensures setting and retrieving clients and resources are *unambiguous and deterministic* operations. By locking the cache, as boto3-client-cache does, race conditions are prevented, enabling developers to confidently employ the 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. From 934b7dc2d877d6589145c8621863607dbf4b164f Mon Sep 17 00:00:00 2001 From: Mike Letts <47342651+michaelthomasletts@users.noreply.github.com> Date: Fri, 24 Jul 2026 18:07:55 -0400 Subject: [PATCH 2/5] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 35b4a83..173268f 100644 --- a/README.md +++ b/README.md @@ -158,8 +158,7 @@ s3_client = cache[key] Errors for resources are identical to errors for clients, except that the word "Client" is replaced with "Resource" in the exception name. ```python -# raises ClientCacheExistsError b/c client(**kwargs) already exists -# from the pseudo-code above +# raises ClientCacheExistsError b/c client(**kwargs) already exists (from the pseudo-code above) cache[key] = boto3.client(**kwargs) # raises ClientCacheNotFoundError b/c the specific client was not From 667095c8f152e6a172c960cd3d8914dc58108dda Mon Sep 17 00:00:00 2001 From: Mike Letts <47342651+michaelthomasletts@users.noreply.github.com> Date: Fri, 24 Jul 2026 18:08:14 -0400 Subject: [PATCH 3/5] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index dfa6780..53af6d3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,7 +33,7 @@ Design The most important but challenging design choice for client and resource caching is selecting and enforcing a robust and standardized methodology for unique keys. **boto3-client-cache hashes according to boto3 client and resource signatures**. -Setting and retrieving clients and resources from the cache therefore requires an explicit declaration of intention — that is, *the developer must explicitly pass client or resource initialization parameters to a ClientCacheKey or ResourceCacheKey object in order to set or retrieve boto3 clients or resources*. +Setting and retrieving clients and resources from the cache therefore requires an explicit declaration of intention — that is, *the developer must explicitly pass client or resource initialization parameters to a ClientCacheKey or ResourceCacheKey object in order to set or retrieve boto3 clients or resources*. This ensures setting and retrieving clients and resources are *unambiguous and deterministic* operations. By locking the cache, as boto3-client-cache does, race conditions are prevented, enabling developers to confidently employ the 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. From 7e6613615c9c1fbb96e23d182f7f4bc38e94b80b Mon Sep 17 00:00:00 2001 From: Mike Letts <47342651+michaelthomasletts@users.noreply.github.com> Date: Fri, 24 Jul 2026 18:10:58 -0400 Subject: [PATCH 4/5] Update README.md --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 173268f..2c22cc6 100644 --- a/README.md +++ b/README.md @@ -158,7 +158,8 @@ s3_client = cache[key] Errors for resources are identical to errors for clients, except that the word "Client" is replaced with "Resource" in the exception name. ```python -# raises ClientCacheExistsError b/c client(**kwargs) already exists (from the pseudo-code above) +# raises ClientCacheExistsError b/c client(**kwargs) already exists +# (from the pseudo-code above) cache[key] = boto3.client(**kwargs) # raises ClientCacheNotFoundError b/c the specific client was not From 68e4b55703234cb0b8aac383841dd81efa125eb4 Mon Sep 17 00:00:00 2001 From: Mike Letts <47342651+michaelthomasletts@users.noreply.github.com> Date: Fri, 24 Jul 2026 18:11:58 -0400 Subject: [PATCH 5/5] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2c22cc6..18f29eb 100644 --- a/README.md +++ b/README.md @@ -158,11 +158,11 @@ s3_client = cache[key] Errors for resources are identical to errors for clients, except that the word "Client" is replaced with "Resource" in the exception name. ```python -# raises ClientCacheExistsError b/c client(**kwargs) already exists +# raises ClientCacheExistsError b/c client(**kwargs) already exists # (from the pseudo-code above) cache[key] = boto3.client(**kwargs) -# raises ClientCacheNotFoundError b/c the specific client was not +# raises ClientCacheNotFoundError b/c the specific client was not # cached above cache[ClientCacheKey(service_name="ec2", region_name="us-west-2")]