[minor] Created sts module (#56)

* New sts module and doc updates

* added missing branch declaration in update-readme.yml

Author: michaelthomasletts

.github/workflows/update-readme.yml

@@ -5,6 +5,8 @@ on:
     - cron: "0 11 * * *"  # 6 AM EST = 11 AM UTC
   workflow_dispatch:
   push:
+    branches:
+      - main
     paths:
       - .github/workflows/update-readme.yml
       - readme.py

.pre-commit-config.yaml

@@ -25,7 +25,7 @@ repos:
     name: pytest
     alias: pytest
     types: [python]
-    entry: python -m pytest -v tests/
+    entry: python -m pytest -v tests/ -s
     language: system
     always_run: true
     pass_filenames: false

README.md

@@ -56,28 +56,23 @@
 - Drop-in replacement for `boto3.session.Session`
 - Supports `assume_role` configuration, custom STS clients, and profile / region configuration, as well as all other parameters supported by `boto3.session.Session`
 - Tested, documented, and published to PyPI
-- Used in production at major tech companies
 
-## Adoption and Recognition
+## Recognition, Adoption, and Testimonials
 
-[Mentioned in TL;DR Sec](https://tldrsec.com/p/tldr-sec-282).
+[Featured in TL;DR Sec.](https://tldrsec.com/p/tldr-sec-282)
 
-Received honorable mention during AWS Community Day Midwest on June 5th, 2025.
+Recognized during AWS Community Day Midwest on June 5th, 2025.
 
-Used by multiple teams and large companies including FAANG.
+A testimonial from a Cyber Security Engineer at a FAANG company:
 
-The following line plot illustrates the adoption of BRS from the last three months in terms of average daily downloads over a rolling seven day window.
+> _Most of my work is on tooling related to AWS security, so I'm pretty choosy about boto3 credentials-adjacent code. I often opt to just write this sort of thing myself so I at least know that I can reason about it. But I found boto3-refresh-session to be very clean and intuitive [...] We're using the RefreshableSession class as part of a client cache construct [...] We're using AWS Lambda to perform lots of operations across several regions in hundreds of accounts, over and over again, all day every day. And it turns out that there's a surprising amount of overhead to creating boto3 clients (mostly deserializing service definition json), so we can run MUCH more efficiently if we keep a cache of clients, all equipped with automatically refreshing sessions._
+
+The following line plot illustrates the adoption of BRS over the last three months in terms of average daily downloads over a rolling seven day window.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/michaelthomasletts/boto3-refresh-session/refs/heads/main/doc/downloads.png" />
 </p>
 
-## Testimonials
-
-From a Cyber Security Engineer at a FAANG company:
-
-> _Most of my work is on tooling related to AWS security, so I'm pretty choosy about boto3 credentials-adjacent code. I often opt to just write this sort of thing myself so I at least know that I can reason about it. But I found boto3-refresh-session to be very clean and intuitive [...] We're using the RefreshableSession class as part of a client cache construct [...] We're using AWS Lambda to perform lots of operations across several regions in hundreds of accounts, over and over again, all day every day. And it turns out that there's a surprising amount of overhead to creating boto3 clients (mostly deserializing service definition json), so we can run MUCH more efficiently if we keep a cache of clients, all equipped with automatically refreshing sessions._
-
 ## Installation
 
 ```bash
@@ -125,27 +120,28 @@ buckets = s3.list_buckets()
 
 ## Raison d'être
 
-It is common for data pipelines and workflows that interact with the AWS API via 
-`boto3` to run for a long time and, accordingly, for temporary credentials to 
-expire. 
+Long-running data pipelines, security tooling, ETL jobs, and cloud automation scripts frequently interact with the AWS API using boto3 — and often run into the same problem:
+
+**Temporary credentials expire.**
+
+When that happens, engineers typically fall back on one of two strategies:
+
+- Wrapping AWS calls in try/except blocks that catch ClientError exceptions
+- Writing ad hoc logic to refresh credentials using botocore credentials internals
 
-Usually, engineers deal with that problem one of two ways: 
+Both approaches are fragile, tedious to maintain, and error-prone at scale.
 
-- `try except` blocks that catch `ClientError` exceptions
-- A similar approach as that used in this project -- that is, using methods available 
-  within `botocore` for refreshing temporary credentials automatically. 
-  
-Speaking personally, variations of the code found herein exists in code bases at 
-nearly every company where I have worked. Sometimes, I turned that code into a module; 
-other times, I wrote it from scratch. Clearly, that is inefficient.
+Over the years, I noticed that every company I worked for — whether a scrappy startup or FAANG — ended up with some variation of the same pattern:  
+a small in-house module to manage credential refresh, written in haste, duplicated across services, and riddled with edge cases. Things only 
+got more strange and difficult when I needed to run things in parallel.
 
-I decided to finally turn that code into a proper Python package with unit testing, 
-automatic documentation, and quality checks; the idea being that, henceforth, depending 
-on my employer's open source policy, I may simply import this package instead of 
-reproducing the code herein for the Nth time.
+Eventually, I decided to build boto3-refresh-session as a proper open-source Python package:  
 
-If any of that sounds relatable, then `boto3-refresh-session` should help you.
+- Fully tested  
+- Extensible  
+- Integrated with boto3 idioms  
+- Equipped with automatic documentation and CI tooling  
 
----
+**The goal:** to solve a real, recurring problem once — cleanly, consistently, and for everyone -- with multiple refresh strategies.
 
-📄 Licensed under the MIT License.
+If you've ever written the same AWS credential-refresh boilerplate more than once, this library is for you. 

README.template.md

@@ -56,28 +56,23 @@
 - Drop-in replacement for `boto3.session.Session`
 - Supports `assume_role` configuration, custom STS clients, and profile / region configuration, as well as all other parameters supported by `boto3.session.Session`
 - Tested, documented, and published to PyPI
-- Used in production at major tech companies
 
-## Adoption and Recognition
+## Recognition, Adoption, and Testimonials
 
-[Mentioned in TL;DR Sec](https://tldrsec.com/p/tldr-sec-282).
+[Featured in TL;DR Sec.](https://tldrsec.com/p/tldr-sec-282)
 
-Received honorable mention during AWS Community Day Midwest on June 5th, 2025.
+Recognized during AWS Community Day Midwest on June 5th, 2025.
 
-Used by multiple teams and large companies including FAANG.
+A testimonial from a Cyber Security Engineer at a FAANG company:
 
-The following line plot illustrates the adoption of BRS from the last three months in terms of average daily downloads over a rolling seven day window.
+> _Most of my work is on tooling related to AWS security, so I'm pretty choosy about boto3 credentials-adjacent code. I often opt to just write this sort of thing myself so I at least know that I can reason about it. But I found boto3-refresh-session to be very clean and intuitive [...] We're using the RefreshableSession class as part of a client cache construct [...] We're using AWS Lambda to perform lots of operations across several regions in hundreds of accounts, over and over again, all day every day. And it turns out that there's a surprising amount of overhead to creating boto3 clients (mostly deserializing service definition json), so we can run MUCH more efficiently if we keep a cache of clients, all equipped with automatically refreshing sessions._
+
+The following line plot illustrates the adoption of BRS over the last three months in terms of average daily downloads over a rolling seven day window.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/michaelthomasletts/boto3-refresh-session/refs/heads/main/doc/downloads.png" />
 </p>
 
-## Testimonials
-
-From a Cyber Security Engineer at a FAANG company:
-
-> _Most of my work is on tooling related to AWS security, so I'm pretty choosy about boto3 credentials-adjacent code. I often opt to just write this sort of thing myself so I at least know that I can reason about it. But I found boto3-refresh-session to be very clean and intuitive [...] We're using the RefreshableSession class as part of a client cache construct [...] We're using AWS Lambda to perform lots of operations across several regions in hundreds of accounts, over and over again, all day every day. And it turns out that there's a surprising amount of overhead to creating boto3 clients (mostly deserializing service definition json), so we can run MUCH more efficiently if we keep a cache of clients, all equipped with automatically refreshing sessions._
-
 ## Installation
 
 ```bash
@@ -125,27 +120,28 @@ buckets = s3.list_buckets()
 
 ## Raison d'être
 
-It is common for data pipelines and workflows that interact with the AWS API via 
-`boto3` to run for a long time and, accordingly, for temporary credentials to 
-expire. 
+Long-running data pipelines, security tooling, ETL jobs, and cloud automation scripts frequently interact with the AWS API using boto3 — and often run into the same problem:
+
+**Temporary credentials expire.**
+
+When that happens, engineers typically fall back on one of two strategies:
+
+- Wrapping AWS calls in try/except blocks that catch ClientError exceptions
+- Writing ad hoc logic to refresh credentials using botocore credentials internals
 
-Usually, engineers deal with that problem one of two ways: 
+Both approaches are fragile, tedious to maintain, and error-prone at scale.
 
-- `try except` blocks that catch `ClientError` exceptions
-- A similar approach as that used in this project -- that is, using methods available 
-  within `botocore` for refreshing temporary credentials automatically. 
-  
-Speaking personally, variations of the code found herein exists in code bases at 
-nearly every company where I have worked. Sometimes, I turned that code into a module; 
-other times, I wrote it from scratch. Clearly, that is inefficient.
+Over the years, I noticed that every company I worked for — whether a scrappy startup or FAANG — ended up with some variation of the same pattern:  
+a small in-house module to manage credential refresh, written in haste, duplicated across services, and riddled with edge cases. Things only 
+got more strange and difficult when I needed to run things in parallel.
 
-I decided to finally turn that code into a proper Python package with unit testing, 
-automatic documentation, and quality checks; the idea being that, henceforth, depending 
-on my employer's open source policy, I may simply import this package instead of 
-reproducing the code herein for the Nth time.
+Eventually, I decided to build boto3-refresh-session as a proper open-source Python package:  
 
-If any of that sounds relatable, then `boto3-refresh-session` should help you.
+- Fully tested  
+- Extensible  
+- Integrated with boto3 idioms  
+- Equipped with automatic documentation and CI tooling  
 
----
+**The goal:** to solve a real, recurring problem once — cleanly, consistently, and for everyone -- with multiple refresh strategies.
 
-📄 Licensed under the MIT License.
+If you've ever written the same AWS credential-refresh boilerplate more than once, this library is for you. 

boto3_refresh_session/__init__.py

@@ -1,8 +1,6 @@
-__all__ = []
-
-from . import session
 from .session import RefreshableSession
+from .sts import STSRefreshableSession
 
-__all__.extend(session.__all__)
+__all__ = ["RefreshableSession"]
 __version__ = "1.0.41"
 __author__ = "Mike Letts"