boto3-refresh-session 1.3.4__py3-none-any.whl → 1.3.6__py3-none-any.whl

boto3_refresh_session/__init__.py

@@ -3,5 +3,5 @@ from .session import RefreshableSession
 from .sts import STSRefreshableSession
 
 __all__ = ["RefreshableSession"]
-__version__ = "1.3.4"
+__version__ = "1.3.6"
 __author__ = "Mike Letts"

{boto3_refresh_session-1.3.4.dist-info → boto3_refresh_session-1.3.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: boto3-refresh-session
-Version: 1.3.4
+Version: 1.3.6
 Summary: A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.
 License: MIT
 Keywords: boto3,botocore,aws
@@ -100,35 +100,33 @@ A testimonial 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._
 
-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.
-
 ## Installation
 
 ```bash
 pip install boto3-refresh-session
 ```
 
-## Usage
+## Usage (STS)
 
 ```python
 import boto3_refresh_session as brs
 
-# you can pass all of the params associated with boto3.session.Session
-profile_name = '<your-profile-name>'
-region_name = 'us-east-1'
+# you can pass all of the params normally associated with boto3.session.Session
+profile_name = "<your-profile-name>"
+region_name = "us-east-1"
 ...
 
 # as well as all of the params associated with STS.Client.assume_role
 assume_role_kwargs = {
-  'RoleArn': '<your-role-arn>',
-  'RoleSessionName': '<your-role-session-name>',
-  'DurationSeconds': '<your-selection>',
+  "RoleArn": "<your-role-arn>",
+  "RoleSessionName": "<your-role-session-name>",
+  "DurationSeconds": "<your-selection>",
   ...
 }
 
 # as well as all of the params associated with STS.Client, except for 'service_name'
 sts_client_kwargs = {
-  'region_name': region_name,
+  "region_name": region_name,
   ...
 }
 
@@ -140,37 +138,41 @@ session = brs.RefreshableSession(
   profile_name=profile_name,
   ...
 )
-
-# now you can create clients, resources, etc. without worrying about expired temporary 
-# security credentials
-s3 = session.client(service_name='s3')
-buckets = s3.list_buckets()
 ```
 
-## Raison d'être
-
-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
-
-Both approaches are fragile, tedious to maintain, and error-prone at scale.
-
-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.
+## Usage (ECS)
 
-Eventually, I decided to build boto3-refresh-session as a proper open-source Python package:  
+```python
+session = RefreshableSession(
+  method="ecs", 
+  region_name=region_name, 
+  profile_name=profile_name,
+  ...
+)
+```
 
-- Fully tested  
-- Extensible  
-- Integrated with boto3 idioms  
-- Equipped with automatic documentation and CI tooling  
+## Usage (Custom)
 
-**The goal:** to solve a real, recurring problem once — cleanly, consistently, and for everyone - with multiple refresh strategies.
+If you have a highly sophisticated, novel, or idiosyncratic authentication flow not included in boto3-refresh-session then you will need to provide your own custom temporary credentials method. `RefreshableSession` accepts custom credentials methods, as shown below.
 
-If you've ever written the same AWS credential-refresh boilerplate more than once, this library is for you. 
+```python
+# create (or import) your custom credential method
+def your_custom_credential_getter(...):
+    ...
+    return {
+        "access_key": ...,
+        "secret_key": ...,
+        "token": ...,
+        "expiry_time": ...,
+    }
+
+# and pass it to RefreshableSession
+session = RefreshableSession(
+    method="custom",
+    custom_credentials_method=your_custom_credential_getter,
+    custom_credentials_methods_args=...,
+    region_name=region_name,
+    profile_name=profile_name,
+    ...
+)
+```

{boto3_refresh_session-1.3.4.dist-info → boto3_refresh_session-1.3.6.dist-info}/RECORD

@@ -1,11 +1,11 @@
-boto3_refresh_session/__init__.py,sha256=CKuebAI3ak--HtZHABu7NmtisPYZvx27UyPay98xCOc,200
+boto3_refresh_session/__init__.py,sha256=944rMVW-eSGvXJhL0-LFD1qSsN1e604qkP6dst8D_-4,200
 boto3_refresh_session/custom.py,sha256=ZnN94A69Eku9L-kHZ7JJxn_aWbrt6mJDWOIEWrJrIcY,3229
 boto3_refresh_session/ecs.py,sha256=WIC5mlbcEnM1oo-QXmmtiw2mjFDn01hBfcFh67ku42A,3713
 boto3_refresh_session/exceptions.py,sha256=qcFzdIuK5PZirs77H_Kb64S9QFb6cn2OJtirjvaRLiY,972
 boto3_refresh_session/session.py,sha256=ak8lvgoHMObaJgL4c80ih4bptRHS3ASojnaWdbxn5kA,5246
 boto3_refresh_session/sts.py,sha256=paIgbmn9a3cATNX-6AEGxnSGNZnX1pj4rRQmh8gQSKs,3132
-boto3_refresh_session-1.3.4.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
-boto3_refresh_session-1.3.4.dist-info/METADATA,sha256=Nwbut9vTqmaEGvGrblAy4k6RXOTrMy1w_L3dlH0E43o,7800
-boto3_refresh_session-1.3.4.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
-boto3_refresh_session-1.3.4.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-boto3_refresh_session-1.3.4.dist-info/RECORD,,
+boto3_refresh_session-1.3.6.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
+boto3_refresh_session-1.3.6.dist-info/METADATA,sha256=noSVW3kcFe92PA5JXoM1qwIt3xgrtVePNNIJiPwDjX4,7034
+boto3_refresh_session-1.3.6.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
+boto3_refresh_session-1.3.6.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+boto3_refresh_session-1.3.6.dist-info/RECORD,,