boto3-refresh-session 3.0.1__py3-none-any.whl → 3.0.2__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__ = "3.0.1"
+__version__ = "3.0.2"
 __title__ = "boto3-refresh-session"
 __author__ = "Mike Letts"
 __maintainer__ = "Mike Letts"

{boto3_refresh_session-3.0.1.dist-info → boto3_refresh_session-3.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: boto3-refresh-session
-Version: 3.0.1
+Version: 3.0.2
 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,ecs,credentials,token,refresh
@@ -162,6 +162,72 @@ pip install boto3-refresh-session
 
 ## 📝 Usage
 
+<details>
+  <summary><strong>Clients and Resources (click to expand)</strong></summary>
+
+  ### Clients and Resources
+
+  Most developers who use `boto3` interact primarily with `boto3.client` or `boto3.resource` instead of `boto3.session.Session`. But many developers may not realize that `boto3.session.Session` belies `boto3.client` and `boto3.resource`! In fact, that's precisely what makes `boto3-refresh-session` possible!
+
+  To use the `boto3.client` or `boto3.resource` interface, but with the benefits of `boto3-refresh-session`, you have a few options! 
+  
+  In the following examples, let's assume you want to use STS for retrieving temporary credentials for the sake of simplicity. Let's also focus specifically on `client`. Switching to `resource` follows the same exact idioms as below, except that `client` must be switched to `resource` in the pseudo-code, obviously. If you are not sure how to use `RefreshableSession` for STS (or ECS or custom auth flows) then check the usage instructions in the following sections!
+
+  ##### `RefreshableSession.client` (Recommended)
+
+  So long as you reuse the same `session` object when creating `client` and `resource` objects, this approach can be used everywhere in your code. It is very simple and straight-forward!
+
+  ```python
+  from boto3_refresh_session import RefreshableSession
+
+  assume_role_kwargs = {
+    "RoleArn": "<your-role-arn>",
+    "RoleSessionName": "<your-role-session-name>",
+    "DurationSeconds": "<your-selection>",
+    ...
+  }
+  session = RefreshableSession(assume_role_kwargs=assume_role_kwargs)
+  s3 = session.client("s3")
+  ```  
+
+  ##### `DEFAULT_SESSION`
+
+  This technique can be helpful if you want to use the same instance of `RefreshableSession` everywhere in your code without reference to `boto3_refresh_session`!
+
+  ```python
+  from boto3 import DEFAULT_SESSION, client
+  from boto3_refresh_session import RefreshableSession
+
+  assume_role_kwargs = {
+    "RoleArn": "<your-role-arn>",
+    "RoleSessionName": "<your-role-session-name>",
+    "DurationSeconds": "<your-selection>",
+    ...
+  }
+  DEFAULT_SESSION = RefreshableSession(assume_role_kwargs=assume_role_kwargs)
+  s3 = client("s3")
+  ```
+
+  ##### `botocore_session`
+
+  ```python
+  from boto3 import client
+  from boto3_refresh_session import RefreshableSession
+
+  assume_role_kwargs = {
+    "RoleArn": "<your-role-arn>",
+    "RoleSessionName": "<your-role-session-name>",
+    "DurationSeconds": "<your-selection>",
+    ...
+  }
+  s3 = client(
+    service_name="s3",
+    botocore_session=RefreshableSession(assume_role_kwargs=assume_role_kwargs)
+  )
+  ```  
+
+  </details>
+
 <details>
   <summary><strong>STS (click to expand)</strong></summary>
 
@@ -222,7 +288,7 @@ pip install boto3-refresh-session
 </details>
 
 <details>
-   <summary><strong>Custom authentication flows (click to expand)</strong></summary>
+   <summary><strong>Custom Authentication Flows (click to expand)</strong></summary>
 
   ### Custom
 

{boto3_refresh_session-3.0.1.dist-info → boto3_refresh_session-3.0.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-boto3_refresh_session/__init__.py,sha256=iaw8zTxeQcjE6dJwDv_LOsgf7oR2z590qmEL9XE8JdI,415
+boto3_refresh_session/__init__.py,sha256=U_4KlnYIh6xejqjTcBm2pZ49IcgQDuUKD75f39zaNeI,415
 boto3_refresh_session/exceptions.py,sha256=DumBh6cDVU46eelSNt1CsG2uMSBekSbmhqWEaAWw130,1003
 boto3_refresh_session/methods/__init__.py,sha256=zpVBJIR4P-l4pjE9kMnLGffehPVawY1vLiX2CPcpV7w,352
 boto3_refresh_session/methods/custom.py,sha256=j90Iv1DKdGgP1JNwQfpEhaJDBrB2AtDe8kqI2Mktwlg,4173
@@ -12,8 +12,8 @@ boto3_refresh_session/session.py,sha256=8YAdanwnJUG622Cv9MNKg25uj9ZmMYzRL4xiqH1i
 boto3_refresh_session/utils/__init__.py,sha256=6F2ErbgBT2ZmZwFF3OzvQEd1Vh4XM3kaL6YGMTrcrkQ,156
 boto3_refresh_session/utils/internal.py,sha256=bpKTAF_xdBw1wJPHIG8aGRMiXkSkp7CI9et0U5o3qEI,6103
 boto3_refresh_session/utils/typing.py,sha256=I4VJS1vkRwIRdJF08dZF1YgUed_anviz3hq4hLvPnLw,3537
-boto3_refresh_session-3.0.1.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
-boto3_refresh_session-3.0.1.dist-info/METADATA,sha256=jDNjmE2_DuJb0s-0kCujRb8JdQT6Awsy8NR4I4s7XKk,9228
-boto3_refresh_session-3.0.1.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
-boto3_refresh_session-3.0.1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-boto3_refresh_session-3.0.1.dist-info/RECORD,,
+boto3_refresh_session-3.0.2.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
+boto3_refresh_session-3.0.2.dist-info/METADATA,sha256=ej-tqjXupuJMux1_gMsQa-utAh47q1PFuhwkuT6_8DQ,11846
+boto3_refresh_session-3.0.2.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
+boto3_refresh_session-3.0.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+boto3_refresh_session-3.0.2.dist-info/RECORD,,