boto3-refresh-session 3.0.1__tar.gz → 3.0.3__tar.gz

{boto3_refresh_session-3.0.1 → boto3_refresh_session-3.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: boto3-refresh-session
-Version: 3.0.1
+Version: 3.0.3
 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,12 +162,78 @@ 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>
 
   ### STS
 
-  Most users use AWS STS to assume an IAM role and return a set of temporary security credentials. boto3-refresh-session can be used to ensure those temporary credentials refresh automatically. 
+  Most developers use AWS STS to assume an IAM role and return a set of temporary security credentials. boto3-refresh-session can be used to ensure those temporary credentials refresh automatically. For additional information on the exact parameters that `RefreshableSession` takes for STS, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/sts.py).
 
   ```python
   import boto3_refresh_session as brs
@@ -208,7 +274,7 @@ pip install boto3-refresh-session
 
   ### ECS
 
-  You can use boto3-refresh-session in an ECS container to automatically refresh temporary security credentials.
+  You can use boto3-refresh-session in an ECS container to automatically refresh temporary security credentials. For additional information on the exact parameters that `RefreshableSession` takes for ECS, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/ecs.py).
 
   ```python
   session = RefreshableSession(
@@ -222,11 +288,11 @@ 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
 
-  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 callable object. `RefreshableSession` accepts custom credentials callable objects, as shown below.
+  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 callable object. `RefreshableSession` accepts custom credentials callable objects, as shown below. For additional information on the exact parameters that `RefreshableSession` takes for custom authentication flows, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/custom.py).
 
   ```python
   # create (or import) your custom credential method

{boto3_refresh_session-3.0.1 → boto3_refresh_session-3.0.3}/README.md

@@ -137,12 +137,78 @@ 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>
 
   ### STS
 
-  Most users use AWS STS to assume an IAM role and return a set of temporary security credentials. boto3-refresh-session can be used to ensure those temporary credentials refresh automatically. 
+  Most developers use AWS STS to assume an IAM role and return a set of temporary security credentials. boto3-refresh-session can be used to ensure those temporary credentials refresh automatically. For additional information on the exact parameters that `RefreshableSession` takes for STS, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/sts.py).
 
   ```python
   import boto3_refresh_session as brs
@@ -183,7 +249,7 @@ pip install boto3-refresh-session
 
   ### ECS
 
-  You can use boto3-refresh-session in an ECS container to automatically refresh temporary security credentials.
+  You can use boto3-refresh-session in an ECS container to automatically refresh temporary security credentials. For additional information on the exact parameters that `RefreshableSession` takes for ECS, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/ecs.py).
 
   ```python
   session = RefreshableSession(
@@ -197,11 +263,11 @@ 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
 
-  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 callable object. `RefreshableSession` accepts custom credentials callable objects, as shown below.
+  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 callable object. `RefreshableSession` accepts custom credentials callable objects, as shown below. For additional information on the exact parameters that `RefreshableSession` takes for custom authentication flows, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/custom.py).
 
   ```python
   # create (or import) your custom credential method

{boto3_refresh_session-3.0.1 → boto3_refresh_session-3.0.3}/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.3"
 __title__ = "boto3-refresh-session"
 __author__ = "Mike Letts"
 __maintainer__ = "Mike Letts"

{boto3_refresh_session-3.0.1 → boto3_refresh_session-3.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "boto3-refresh-session"
-version = "3.0.1"
+version = "3.0.3"
 description = "A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically."
 authors = [
     {name = "Mike Letts",email = "lettsmt@gmail.com"}