boto3-refresh-session 1.2.2__py3-none-any.whl → 1.2.4__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.2.2"
+__version__ = "1.2.4"
 __author__ = "Mike Letts"

boto3_refresh_session/custom.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+__all__ = ["CustomRefreshableSession"]
+
+from typing import Any, Callable
+
+from .session import BaseRefreshableSession
+
+
+class CustomRefreshableSession(BaseRefreshableSession, method="custom"):
+    """A :class:`boto3.session.Session` object that automatically refreshes temporary credentials
+    returned by a custom credential getter provided by the user. Useful for users with highly
+    sophisticated or idiosyncratic authentication flows.
+
+    Parameters
+    ----------
+    custom_credentials_method: Callable
+        Required. Accepts a Python function that returns temporary AWS security credentials. That
+        function must return a dictionary containing 'access_key', 'secret_key', 'token', and
+        'expiry_time' when called.
+    custom_credentials_method_args : dict[str, Any], optional
+        Optional keyword arguments for the function passed to the ``custom_credentials_method``
+        parameter.
+    defer_refresh : bool, optional
+        If ``True`` then temporary credentials are not automatically refreshed until
+        they are explicitly needed. If ``False`` then temporary credentials refresh
+        immediately upon expiration. It is highly recommended that you use ``True``.
+        Default is ``True``.
+
+    Other Parameters
+    ----------------
+    kwargs : dict
+        Optional keyword arguments for the :class:`boto3.session.Session` object.
+
+    Examples
+    --------
+    Write (or import) the method for obtaining temporary AWS security credentials.
+    
+    >>> def your_custom_credential_getter(your_param, another_param):
+    >>>     ...
+    >>>     return {
+    >>>         'access_key': ...,
+    >>>         'secret_key': ...,
+    >>>         'token': ...,
+    >>>         'expiry_time': ...,
+    >>>     }
+
+    Pass that method to ``RefreshableSession``.
+
+    >>> sess = RefreshableSession(
+    >>>     method='custom',
+    >>>     custom_credentials_method=your_custom_credential_getter,
+    >>>     custom_credentials_methods_args=...,
+    >>> )
+    """
+
+    def __init__(
+        self,
+        custom_credentials_method: Callable,
+        custom_credentials_method_args: dict[str, Any] | None = None,
+        defer_refresh: bool | None = None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+
+        self._custom_get_credentials = custom_credentials_method
+        self._custom_get_credentials_args = (
+            custom_credentials_method_args
+            if custom_credentials_method_args is not None
+            else {}
+        )
+
+        self._refresh_using(
+            credentials_method=self._get_credentials,
+            defer_refresh=defer_refresh is not False,
+            refresh_method="custom",
+        )
+
+    def _get_credentials(self) -> dict[str, str]:
+        return self._custom_get_credentials(
+            **self._custom_get_credentials_args
+        )
+
+    def get_identity(self):
+        """Returns metadata about the custom credential getter.
+
+        Returns
+        -------
+        dict[str, str]
+            Dict containing information about the custom credential getter.
+        """
+
+        return {
+            "method": "custom",
+            "source": repr(self._custom_get_credentials.__name__),
+        }

boto3_refresh_session/session.py

@@ -14,8 +14,8 @@ from botocore.credentials import (
 from .exceptions import BRSError, BRSWarning
 
 #: Type alias for all currently available credential refresh methods.
-Method = Literal["sts", "ecs"]
-RefreshMethod = Literal["sts-assume-role", "ecs-container-metadata"]
+Method = Literal["sts", "ecs", "custom"]
+RefreshMethod = Literal["sts-assume-role", "ecs-container-metadata", "custom"]
 
 
 class BaseRefreshableSession(ABC, Session):

{boto3_refresh_session-1.2.2.dist-info → boto3_refresh_session-1.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: boto3-refresh-session
-Version: 1.2.2
+Version: 1.2.4
 Summary: A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.
 License: MIT
 Keywords: boto3,botocore,aws
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
   </a>
 
   <a href="https://pepy.tech/project/boto3-refresh-session">
-    <img src="https://img.shields.io/badge/downloads-59.8K-red?logo=python&color=%23FF0000&label=Downloads" alt="Downloads"/>
+    <img src="https://img.shields.io/badge/downloads-62.9K-red?logo=python&color=%23FF0000&label=Downloads" alt="Downloads"/>
   </a>
 
   <a href="https://michaelthomasletts.github.io/boto3-refresh-session/index.html">
@@ -71,12 +71,16 @@ Description-Content-Type: text/markdown
     <img src="https://img.shields.io/badge/Q%26A-❔-FF0000?style=flat&labelColor=555&logo=vercel&label=Q%26A" alt="Q&A Badge"/>
   </a>
 
+  <a href="https://medium.com/@lettsmt/you-shouldnt-have-to-think-about-refreshing-aws-credentials-214f7cbbd83b">
+    <img src="https://img.shields.io/badge/Medium%20Article-📘-FF0000?style=flat&labelColor=555&logo=readthedocs" alt="Medium Article"/>
+  </a>    
+
 </div>
 
 ## Features
 
 - Drop-in replacement for `boto3.session.Session`
-- Supports automatic credential refresh methods for the following AWS services:
+- Supports automatic credential refresh methods for various AWS services:
   - STS
   - ECS
 - Supports `assume_role` configuration, custom STS clients, and profile / region configuration, as well as all other parameters supported by `boto3.session.Session`

boto3_refresh_session-1.2.4.dist-info/RECORD

@@ -0,0 +1,11 @@
+boto3_refresh_session/__init__.py,sha256=xC5R29qlAHd-N5HGJ5UnlYSQjQYWKwHvnAXi2aLcAQY,200
+boto3_refresh_session/custom.py,sha256=IZ5D0mf1FP3OsdZoctwsXKNeDPRv5Ks03Iyt4qOcdyA,3233
+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.2.4.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
+boto3_refresh_session-1.2.4.dist-info/METADATA,sha256=fu1UvMUHKLjodms2cpYHcsD1_MmWXgvm1jlFk6XjvrQ,7898
+boto3_refresh_session-1.2.4.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
+boto3_refresh_session-1.2.4.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+boto3_refresh_session-1.2.4.dist-info/RECORD,,

boto3_refresh_session-1.2.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-boto3_refresh_session/__init__.py,sha256=GxjBuAEtnvwoSO-PQOvzG0IK6LlO84zbabISpX3Mh3A,200
-boto3_refresh_session/ecs.py,sha256=WIC5mlbcEnM1oo-QXmmtiw2mjFDn01hBfcFh67ku42A,3713
-boto3_refresh_session/exceptions.py,sha256=qcFzdIuK5PZirs77H_Kb64S9QFb6cn2OJtirjvaRLiY,972
-boto3_refresh_session/session.py,sha256=MtaTVdAy-Yx7x_x9SUJ0FlQs0w_8D3kHjvOS8C3bK2E,5226
-boto3_refresh_session/sts.py,sha256=paIgbmn9a3cATNX-6AEGxnSGNZnX1pj4rRQmh8gQSKs,3132
-boto3_refresh_session-1.2.2.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
-boto3_refresh_session-1.2.2.dist-info/METADATA,sha256=eW0320X2RCmISQ-UotSbSWp5s2DVEA90z7iR-SMt7ro,7639
-boto3_refresh_session-1.2.2.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
-boto3_refresh_session-1.2.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-boto3_refresh_session-1.2.2.dist-info/RECORD,,