boto3-refresh-session 5.1.4__py3-none-any.whl → 5.1.6__py3-none-any.whl

boto3_refresh_session/__init__.py

@@ -9,7 +9,7 @@ from .session import *
 
 __all__.extend(session.__all__)
 __all__.extend(exceptions.__all__)
-__version__ = "5.1.4"
+__version__ = "5.1.6"
 __title__ = "boto3-refresh-session"
 __author__ = "Mike Letts"
 __maintainer__ = "Mike Letts"

{boto3_refresh_session-5.1.4.dist-info → boto3_refresh_session-5.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: boto3-refresh-session
-Version: 5.1.4
+Version: 5.1.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,sts,credentials,token,refresh,iot,x509,mqtt
@@ -152,6 +152,25 @@ pip install boto3-refresh-session
 
 ## 📝 Usage
 
+<details>
+  <summary><strong>Core Concepts (click to expand)</strong></summary>
+
+  ### Core Concepts
+
+  1. `RefreshableSession` is the intended interface for using `boto3-refresh-session`. Whether you're using this package to refresh temporary credentials returned by STS, the IoT credential provider (which is really just STS, but I digress), or some custom authentication or credential provider, `RefreshableSession` is where you *ought to* be working when using `boto3-refresh-session`.
+
+  2. *You can use all of the same keyword parameters normally associated with `boto3.session.Session`!* For instance, suppose you want to pass `region_name` to `RefreshableSession` as a parameter, whereby it's passed to `boto3.session.Session`. That's perfectly fine! Just pass it like you normally would when initializing `boto3.session.Session`. These keyword parameters are *completely optional*, though. If you're confused, the main idea to remember is this: if initializing `boto3.session.Session` *requires* a particular keyword parameter then pass it to `RefreshableSession`; if not, don't worry about it.
+
+  3. To tell `RefreshableSession` which AWS service you're working with for authentication and credential retrieval purposes (STS vs. IoT vs. some custom credential provider), you'll need to pass a `method` parameter to `RefreshableSession`. Since the `service_name` namespace is already occupied by `boto3.sesssion.Session`, [`boto3-refresh-session` uses `method` instead of "service" so as to avoid confusion](https://github.com/michaelthomasletts/boto3-refresh-session/blob/04acb2adb34e505c4dc95711f6b2f97748a2a489/boto3_refresh_session/utils/typing.py#L40). If you're using `RefreshableSession` for STS, however, then `method` is set to `"sts"` by default. You don't need to pass the `method` keyword argument in that case.
+
+  4. Using `RefreshableSession` for STS, IoT, or custom flows requires different keyword parameters that are unique to those particular methods. For instance, `STSRefreshableSession`, which is the engine for STS in `boto3-refresh-session`, requires `assume_role_kwargs` and optionally allows `sts_client_kwargs` whereas `CustomRefreshableSession` and `IoTX509RefreshableSession` do not. To familiarize yourself with the keyword parameters for each method, check the documentation for each of those engines [in the Refresh Strategies section here](https://michaelthomasletts.com/boto3-refresh-session/modules/index.html).
+
+  5. Irrespective of whatever `method` you pass as a keyword parameter, `RefreshableSession` accepts a keyword parameter named `defer_refresh`. Basically, this boolean tells `boto3-refresh-session` either to refresh credentials *the moment they expire* or to *wait until credentials are explicitly needed*. If you are working in a low-latency environment then `defer_refresh = False` might be helpful. For most users, however, `defer_refresh = True` is most desirable. For that reason, `defer_refresh = True` is the default value. Most users, therefore, should not concern themselves too much with this feature.
+
+  6. Some developers struggle to imagine where `boto3-refresh-session` might be helpful. To figure out if `boto3-refresh-session` is for your use case, or whether `credential_process` satisfies your needs, check out [this blog post](https://michaelthomasletts.com/blog/brs-rationale/). `boto3-refresh-session` is not for every developer or use-case; it is a niche tool. 
+
+</details>
+
 <details>
   <summary><strong>Clients and Resources (click to expand)</strong></summary>
 
@@ -228,12 +247,12 @@ pip install boto3-refresh-session
   ```python
   import boto3_refresh_session as brs
 
-  # you can pass all of the params normally associated with boto3.session.Session
+  # OPTIONAL - 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
+  # REQUIRED - 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>",
@@ -241,7 +260,7 @@ pip install boto3-refresh-session
     ...
   }
 
-  # as well as all of the params associated with STS.Client, except for 'service_name'
+  # OPTIONAL - as well as all of the params associated with STS.Client, except for 'service_name'
   sts_client_kwargs = {
     "region_name": region_name,
     ...
@@ -250,10 +269,10 @@ pip install boto3-refresh-session
   # basic initialization of boto3.session.Session
   session = brs.RefreshableSession(
     assume_role_kwargs=assume_role_kwargs, # required
-    sts_client_kwargs=sts_client_kwargs,
-    region_name=region_name,
-    profile_name=profile_name,
-    ...
+    sts_client_kwargs=sts_client_kwargs,   # optional
+    region_name=region_name,               # optional
+    profile_name=profile_name,             # optional
+    ...                                    # misc. params for boto3.session.Session
   )
   ```
 
@@ -279,12 +298,12 @@ pip install boto3-refresh-session
 
   # and pass it to RefreshableSession
   session = RefreshableSession(
-      method="custom",
-      custom_credentials_method=your_custom_credential_getter,
-      custom_credentials_method_args=...,
-      region_name=region_name,
-      profile_name=profile_name,
-      ...
+      method="custom",                                         # required
+      custom_credentials_method=your_custom_credential_getter, # required
+      custom_credentials_method_args=...,                      # optional
+      region_name=region_name,                                 # optional
+      profile_name=profile_name,                               # optional
+      ...                                                      # misc. params for boto3.session.Session
   )
   ```
 

{boto3_refresh_session-5.1.4.dist-info → boto3_refresh_session-5.1.6.dist-info}/RECORD

@@ -1,4 +1,4 @@
-boto3_refresh_session/__init__.py,sha256=3_RcKKPpjrgA1FROjtE9ASDX3RamBQK-HJSPhpn9nF4,415
+boto3_refresh_session/__init__.py,sha256=bKBhRhrlKK1Jzczmcv7SUPbTb9sIBS_7CaMOxZrVsW8,415
 boto3_refresh_session/exceptions.py,sha256=QS5_xy3hNrfkdT_wKPZWH8WqSbFYCKPcK8DomGYIvcU,1218
 boto3_refresh_session/methods/__init__.py,sha256=FpwWixSVpy_6pUe1u4fXmjO-_fDH--qTk_xrMnBCHxU,193
 boto3_refresh_session/methods/custom.py,sha256=MLdUMU9s6NQoJWBKQ5Fsxeyxb_Xrm9V59pVX22M8fyI,4178
@@ -10,8 +10,8 @@ boto3_refresh_session/session.py,sha256=UM_dWHSo0Wn8gLN99zg36SRVb-Yy_to1wk8UgZEu
 boto3_refresh_session/utils/__init__.py,sha256=6F2ErbgBT2ZmZwFF3OzvQEd1Vh4XM3kaL6YGMTrcrkQ,156
 boto3_refresh_session/utils/internal.py,sha256=HbuIzT0pC8QS4pgNj3M7POGaW-OEz2l3ESfYI1Qouuo,7072
 boto3_refresh_session/utils/typing.py,sha256=YbnVYPe-ZEr79THp78u74PzF6LOIxpf91yGsvBmhEBM,3532
-boto3_refresh_session-5.1.4.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
-boto3_refresh_session-5.1.4.dist-info/METADATA,sha256=qlpE3DJIwtrPn6vDWtYcSWnFEqQGPNfaP0tLf_EeTR4,15084
-boto3_refresh_session-5.1.4.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
-boto3_refresh_session-5.1.4.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-boto3_refresh_session-5.1.4.dist-info/RECORD,,
+boto3_refresh_session-5.1.6.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
+boto3_refresh_session-5.1.6.dist-info/METADATA,sha256=S8KRZo0B_4NThrR_71wGPIBNDBDDzTUd9kwNUvIfe3c,18979
+boto3_refresh_session-5.1.6.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
+boto3_refresh_session-5.1.6.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+boto3_refresh_session-5.1.6.dist-info/RECORD,,