boto3-refresh-session 1.0.41__py3-none-any.whl → 1.1.0__py3-none-any.whl

boto3_refresh_session/__init__.py

@@ -1,8 +1,6 @@
-__all__ = []
-
-from . import session
 from .session import RefreshableSession
+from .sts import STSRefreshableSession
 
-__all__.extend(session.__all__)
-__version__ = "1.0.41"
+__all__ = ["RefreshableSession"]
+__version__ = "1.1.0"
 __author__ = "Mike Letts"

boto3_refresh_session/session.py

@@ -1,159 +1,155 @@
 from __future__ import annotations
 
 __doc__ = """
-A :class:`boto3.session.Session` object that automatically refreshes temporary AWS
-credentials.
+boto3_refresh_session.session
+=============================
+
+This module provides the main interface for constructing refreshable boto3 sessions.
+
+The ``RefreshableSession`` class serves as a factory that dynamically selects the appropriate 
+credential refresh strategy based on the ``method`` parameter, e.g., ``sts``.
+
+Users can interact with AWS services just like they would with a normal :class:`boto3.session.Session`, 
+with the added benefit of automatic credential refreshing.
+
+Examples
+--------
+>>> from boto3_refresh_session import RefreshableSession
+>>> session = RefreshableSession(
+...     assume_role_kwargs={"RoleArn": "...", "RoleSessionName": "..."},
+...     region_name="us-east-1"
+... )
+>>> s3 = session.client("s3")
+>>> s3.list_buckets()
+
+.. seealso::
+    :class:`boto3_refresh_session.sts.STSRefreshableSession`
+
+Factory interface
+-----------------
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   RefreshableSession
 """
+
 __all__ = ["RefreshableSession"]
 
-from typing import Any, Dict
+from abc import ABC, abstractmethod
+from typing import Any, Callable, ClassVar, Literal, get_args
 from warnings import warn
 
-from boto3 import client
 from boto3.session import Session
 from botocore.credentials import (
     DeferredRefreshableCredentials,
     RefreshableCredentials,
 )
 
+#: Type alias for all currently available credential refresh methods.
+Method = Literal["sts"]
+RefreshMethod = Literal["sts-assume-role"]
+
+
+class BaseRefreshableSession(ABC, Session):
+    """Abstract base class for implementing refreshable AWS sessions.
 
-class RefreshableSession(Session):
-    """A :class:`boto3.session.Session` object that automatically refreshes temporary AWS 
-    credentials.
+    Provides a common interface and factory registration mechanism
+    for subclasses that generate temporary credentials using various
+    AWS authentication methods (e.g., STS).
+
+    Subclasses must implement ``_get_credentials()`` and ``get_identity()``.
+    They should also register themselves using the ``method=...`` argument
+    to ``__init_subclass__``.
 
     Parameters
     ----------
-    assume_role_kwargs : dict
-        Required keyword arguments for the :meth:`STS.Client.assume_role` method.
-    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``.
-    sts_client_kwargs : dict, optional
-        Optional keyword arguments for the :class:`STS.Client` object. Do not provide
-        values for ``service_name``. Default is None.
+    registry : dict[str, type[BaseRefreshableSession]]
+        Class-level registry mapping method names to registered session types.
+    """
 
-    Other Parameters
-    ----------------
-    kwargs : dict
-        Optional keyword arguments for the :class:`boto3.session.Session` object.
+    # adding this and __init_subclass__ to avoid circular imports
+    # as well as simplify future addition of new methods
+    registry: ClassVar[dict[Method, type[BaseRefreshableSession]]] = {}
 
-    Notes
-    -----
-    Check the :ref:`authorization documentation <authorization>` for additional
-    information concerning how to authorize access to AWS.
+    def __init_subclass__(cls, method: Method):
+        super().__init_subclass__()
 
-    Check the `AWS documentation <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html>`_
-    for additional information concerning temporary security credentials in IAM.
+        # guarantees that methods are unique
+        if method in BaseRefreshableSession.registry:
+            warn(f"Method '{method}' is already registered. Overwriting.")
 
-    Examples
-    --------
-    In order to use this object, you are required to configure parameters for the
-    :meth:`STS.Client.assume_role` method.
-
-    >>> assume_role_kwargs = {
-    >>>     'RoleArn': '<your-role-arn>',
-    >>>     'RoleSessionName': '<your-role-session-name>',
-    >>>     'DurationSeconds': '<your-selection>',
-    >>>     ...
-    >>> }
-
-    You may also want to provide optional parameters for the :class:`STS.Client` object.
-
-    >>> sts_client_kwargs = {
-    >>>     ...
-    >>> }
-
-    You may also provide optional parameters for the :class:`boto3.session.Session` object
-    when initializing the ``RefreshableSession`` object. Below, we use the ``region_name``
-    parameter for illustrative purposes.
-
-    >>> session = boto3_refresh_session.RefreshableSession(
-    >>>     assume_role_kwargs=assume_role_kwargs,
-    >>>     sts_client_kwargs=sts_client_kwargs,
-    >>>     region_name='us-east-1',
-    >>> )
-
-    Using the ``session`` variable that you just created, you can now use all of the methods
-    available from the :class:`boto3.session.Session` object. In the below example, we
-    initialize an S3 client and list all available buckets.
-
-    >>> s3 = session.client(service_name='s3')
-    >>> buckets = s3.list_buckets()
-
-    There are two ways of refreshing temporary credentials automatically with the
-    ``RefreshableSession`` object: refresh credentials the moment they expire, or wait until
-    temporary credentials are explicitly needed. The latter is the default. The former must
-    be configured using the ``defer_refresh`` parameter, as shown below.
-
-    >>> session = boto3_refresh_session.RefreshableSession(
-    >>>     defer_refresh=False,
-    >>>     assume_role_kwargs=assume_role_kwargs,
-    >>>     sts_client_kwargs=sts_client_kwargs,
-    >>>     region_name='us-east-1',
-    >>> )
-    """
+        BaseRefreshableSession.registry[method] = cls
 
-    def __init__(
-        self,
-        assume_role_kwargs: Dict[Any],
-        defer_refresh: bool = None,
-        sts_client_kwargs: Dict[Any] = None,
-        **kwargs,
-    ):
-        # inheriting from boto3.session.Session
+    def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
-        # setting defer_refresh default
-        if defer_refresh is None:
-            defer_refresh = True
-
-        # initializing custom parameters that are necessary outside of __init__
-        self.assume_role_kwargs = assume_role_kwargs
-
-        # initializing the STS client
-        if sts_client_kwargs is not None:
-            # overwriting 'service_name' in case it appears in sts_client_kwargs
-            if "service_name" in sts_client_kwargs:
-                warn(
-                    "The sts_client_kwargs parameter cannot contain values for service_name. Reverting to service_name = 'sts'."
-                )
-                del sts_client_kwargs["service_name"]
-            self._sts_client = client(service_name="sts", **sts_client_kwargs)
-        else:
-            self._sts_client = client(service_name="sts")
+    @abstractmethod
+    def _get_credentials(self) -> dict[str, str]: ...
 
+    @abstractmethod
+    def get_identity(self) -> dict[str, Any]: ...
+
+    def _refresh_using(
+        self,
+        credentials_method: Callable,
+        defer_refresh: bool,
+        refresh_method: RefreshMethod,
+    ):
         # determining how exactly to refresh expired temporary credentials
         if not defer_refresh:
-            self._session._credentials = (
-                RefreshableCredentials.create_from_metadata(
-                    metadata=self._get_credentials(),
-                    refresh_using=self._get_credentials,
-                    method="sts-assume-role",
-                )
+            self._credentials = RefreshableCredentials.create_from_metadata(
+                metadata=credentials_method(),
+                refresh_using=credentials_method,
+                method=refresh_method,
             )
         else:
-            self._session._credentials = DeferredRefreshableCredentials(
-                refresh_using=self._get_credentials, method="sts-assume-role"
+            self._credentials = DeferredRefreshableCredentials(
+                refresh_using=credentials_method, method=refresh_method
             )
 
-    def _get_credentials(self) -> Dict[Any]:
-        """Returns temporary credentials via AWS STS.
+
+class RefreshableSession:
+    """Factory class for constructing refreshable boto3 sessions using various authentication
+    methods, e.g. STS.
+
+    This class provides a unified interface for creating boto3 sessions whose credentials are
+    automatically refreshed in the background.
+
+    Use ``RefreshableSession(method="...")`` to construct an instance using the desired method.
+
+    For additional information on required parameters, refer to the See Also section below.
+
+    Parameters
+    ----------
+    method : Method
+        The authentication and refresh method to use for the session. Must match a registered method name.
+        Default is "sts".
+
+    Other Parameters
+    ----------------
+    **kwargs : dict
+        Additional keyword arguments forwarded to the constructor of the selected session class.
+
+    See Also
+    --------
+    boto3_refresh_session.sts.STSRefreshableSession
+    """
+
+    def __new__(
+        cls, method: Method = "sts", **kwargs
+    ) -> BaseRefreshableSession:
+        obj = BaseRefreshableSession.registry[method]
+        return obj(**kwargs)
+
+    @classmethod
+    def get_available_methods(cls) -> list[str]:
+        """Lists all currently available credential refresh methods.
 
         Returns
         -------
-        dict
-            AWS temporary credentials.
+        list[str]
+            A list of all currently available credential refresh methods, e.g. 'sts'.
         """
 
-        # fetching temporary credentials
-        temporary_credentials = self._sts_client.assume_role(
-            **self.assume_role_kwargs
-        )["Credentials"]
-        return {
-            "access_key": temporary_credentials.get("AccessKeyId"),
-            "secret_key": temporary_credentials.get("SecretAccessKey"),
-            "token": temporary_credentials.get("SessionToken"),
-            "expiry_time": temporary_credentials.get("Expiration").isoformat(),
-        }
+        return list(get_args(Method))

boto3_refresh_session/sts.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+__doc__ = """
+boto3_refresh_session.sts
+=========================
+
+Implements the STS-based credential refresh strategy for use with 
+:class:`boto3_refresh_session.session.RefreshableSession`.
+
+This module defines the :class:`STSRefreshableSession` class, which uses 
+IAM role assumption via STS to automatically refresh temporary credentials 
+in the background.
+
+.. versionadded:: 1.1.0
+
+Examples
+--------
+>>> from boto3_refresh_session import RefreshableSession
+>>> session = RefreshableSession(
+...     method="sts",
+...     assume_role_kwargs={
+...         "RoleArn": "arn:aws:iam::123456789012:role/MyRole",
+...         "RoleSessionName": "my-session"
+...     },
+...     region_name="us-east-1"
+... )
+>>> s3 = session.client("s3")
+>>> s3.list_buckets()
+
+.. seealso::
+    :class:`boto3_refresh_session.session.RefreshableSession`
+
+STS
+---    
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   STSRefreshableSession
+"""
+__all__ = ["STSRefreshableSession"]
+
+from typing import Any
+from warnings import warn
+
+from boto3 import client
+
+from .session import BaseRefreshableSession
+
+
+class STSRefreshableSession(BaseRefreshableSession, method="sts"):
+    """A :class:`boto3.session.Session` object that automatically refreshes temporary AWS
+    credentials using an IAM role that is assumed via STS.
+
+    Parameters
+    ----------
+    assume_role_kwargs : dict
+        Required keyword arguments for :meth:`STS.Client.assume_role` (i.e. boto3 STS client).
+    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``.
+    sts_client_kwargs : dict, optional
+        Optional keyword arguments for the :class:`STS.Client` object. Do not provide
+        values for ``service_name`` as they are unnecessary. Default is None.
+
+    Other Parameters
+    ----------------
+    kwargs : dict
+        Optional keyword arguments for the :class:`boto3.session.Session` object.
+    """
+
+    def __init__(
+        self,
+        assume_role_kwargs: dict,
+        defer_refresh: bool = None,
+        sts_client_kwargs: dict | None = None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        defer_refresh = defer_refresh is not False
+        self.assume_role_kwargs = assume_role_kwargs
+
+        if sts_client_kwargs is not None:
+            # overwriting 'service_name' in case it appears in sts_client_kwargs
+            if "service_name" in sts_client_kwargs:
+                warn(
+                    "The sts_client_kwargs parameter cannot contain values for service_name. Reverting to service_name = 'sts'."
+                )
+                del sts_client_kwargs["service_name"]
+            self._sts_client = client(service_name="sts", **sts_client_kwargs)
+        else:
+            self._sts_client = client(service_name="sts")
+
+        # mounting refreshable credentials
+        self._refresh_using(
+            credentials_method=self._get_credentials,
+            defer_refresh=defer_refresh,
+            refresh_method="sts-assume-role",
+        )
+
+    def _get_credentials(self) -> dict[str, str]:
+        temporary_credentials = self._sts_client.assume_role(
+            **self.assume_role_kwargs
+        )["Credentials"]
+        return {
+            "access_key": temporary_credentials.get("AccessKeyId"),
+            "secret_key": temporary_credentials.get("SecretAccessKey"),
+            "token": temporary_credentials.get("SessionToken"),
+            "expiry_time": temporary_credentials.get("Expiration").isoformat(),
+        }
+
+    def get_identity(self) -> dict[str, Any]:
+        """Returns metadata about the identity assumed.
+
+        Returns
+        -------
+        dict[str, Any]
+            Dict containing caller identity according to AWS STS.
+        """
+
+        return self._sts_client.get_caller_identity()

{boto3_refresh_session-1.0.41.dist-info → boto3_refresh_session-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: boto3-refresh-session
-Version: 1.0.41
+Version: 1.1.0
 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-56.7K-red?logo=python&color=%23FF0000&label=Downloads" alt="Downloads"/>
+    <img src="https://img.shields.io/badge/downloads-57.4K-red?logo=python&color=%23FF0000&label=Downloads" alt="Downloads"/>
   </a>
 
   <a href="https://michaelthomasletts.github.io/boto3-refresh-session/index.html">
@@ -79,28 +79,23 @@ Description-Content-Type: text/markdown
 - Drop-in replacement for `boto3.session.Session`
 - Supports `assume_role` configuration, custom STS clients, and profile / region configuration, as well as all other parameters supported by `boto3.session.Session`
 - Tested, documented, and published to PyPI
-- Used in production at major tech companies
 
-## Adoption and Recognition
+## Recognition, Adoption, and Testimonials
 
-[Mentioned in TL;DR Sec](https://tldrsec.com/p/tldr-sec-282).
+[Featured in TL;DR Sec.](https://tldrsec.com/p/tldr-sec-282)
 
-Received honorable mention during AWS Community Day Midwest on June 5th, 2025.
+Recognized during AWS Community Day Midwest on June 5th, 2025.
 
-Used by multiple teams and large companies including FAANG.
+A testimonial from a Cyber Security Engineer at a FAANG company:
 
-The following line plot illustrates the adoption of BRS from the last three months in terms of average daily downloads over a rolling seven day window.
+> _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.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/michaelthomasletts/boto3-refresh-session/refs/heads/main/doc/downloads.png" />
 </p>
 
-## Testimonials
-
-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._
-
 ## Installation
 
 ```bash
@@ -148,27 +143,28 @@ buckets = s3.list_buckets()
 
 ## Raison d'être
 
-It is common for data pipelines and workflows that interact with the AWS API via 
-`boto3` to run for a long time and, accordingly, for temporary credentials to 
-expire. 
+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
 
-Usually, engineers deal with that problem one of two ways: 
+Both approaches are fragile, tedious to maintain, and error-prone at scale.
 
-- `try except` blocks that catch `ClientError` exceptions
-- A similar approach as that used in this project -- that is, using methods available 
-  within `botocore` for refreshing temporary credentials automatically. 
-  
-Speaking personally, variations of the code found herein exists in code bases at 
-nearly every company where I have worked. Sometimes, I turned that code into a module; 
-other times, I wrote it from scratch. Clearly, that is inefficient.
+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.
 
-I decided to finally turn that code into a proper Python package with unit testing, 
-automatic documentation, and quality checks; the idea being that, henceforth, depending 
-on my employer's open source policy, I may simply import this package instead of 
-reproducing the code herein for the Nth time.
+Eventually, I decided to build boto3-refresh-session as a proper open-source Python package:  
 
-If any of that sounds relatable, then `boto3-refresh-session` should help you.
+- Fully tested  
+- Extensible  
+- Integrated with boto3 idioms  
+- Equipped with automatic documentation and CI tooling  
 
----
+**The goal:** to solve a real, recurring problem once — cleanly, consistently, and for everyone -- with multiple refresh strategies.
 
-📄 Licensed under the MIT License.
+If you've ever written the same AWS credential-refresh boilerplate more than once, this library is for you. 

boto3_refresh_session-1.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+boto3_refresh_session/__init__.py,sha256=q_SWX2IjsvgROUhgsVpW3h70mSbnIz1fPIYUbsxJSY8,161
+boto3_refresh_session/session.py,sha256=J3FW6nkc_s9C0gj1Xs1wKaCWQMzR6S4ncDKDqu1DYxk,4879
+boto3_refresh_session/sts.py,sha256=8vUBPTtoqJIgF-NOg4617WbmJ92GiKcmsVDdINieoFo,4043
+boto3_refresh_session-1.1.0.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
+boto3_refresh_session-1.1.0.dist-info/METADATA,sha256=Ny4vrpfNYQdXGuBAkAJW8LPMqO54qysxVHfNsJxCKts,7534
+boto3_refresh_session-1.1.0.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
+boto3_refresh_session-1.1.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+boto3_refresh_session-1.1.0.dist-info/RECORD,,

boto3_refresh_session-1.0.41.dist-info/RECORD

@@ -1,7 +0,0 @@
-boto3_refresh_session/__init__.py,sha256=NryXLl4sSu3AO_-yrcFsiWU09XnHr-ap4-qr39btGLI,158
-boto3_refresh_session/session.py,sha256=ZB1X0ajFZSpuRKi4N3KGg56Y7ZJPMN3jwjMh-6grbvo,5881
-boto3_refresh_session-1.0.41.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
-boto3_refresh_session-1.0.41.dist-info/METADATA,sha256=GJZhfPAymeIm1kWAzY4GDrvO_biuYWVMgp4ep28qclA,7406
-boto3_refresh_session-1.0.41.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
-boto3_refresh_session-1.0.41.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-boto3_refresh_session-1.0.41.dist-info/RECORD,,