boto3-refresh-session 1.0.36__py3-none-any.whl → 6.2.7__py3-none-any.whl

boto3_refresh_session/__init__.py

@@ -1,8 +1,17 @@
 __all__ = []
 
-from . import session
-from .session import RefreshableSession
+from . import exceptions, session
+from .exceptions import *
+from .methods.custom import *
+from .methods.iot import *
+from .methods.sts import *
+from .session import *
 
 __all__.extend(session.__all__)
-__version__ = "1.0.36"
+__all__.extend(exceptions.__all__)
+__version__ = "6.2.7"
+__title__ = "boto3-refresh-session"
 __author__ = "Mike Letts"
+__maintainer__ = "Mike Letts"
+__license__ = "MIT"
+__email__ = "lettsmt@gmail.com"

boto3_refresh_session/exceptions.py

@@ -0,0 +1,51 @@
+"""Custom exception and warning types for boto3-refresh-session."""
+
+__all__ = ["BRSError", "BRSWarning"]
+
+import warnings
+
+
+class BRSError(Exception):
+    """The base exception for boto3-refresh-session.
+
+    Parameters
+    ----------
+    message : str, optional
+        The message to raise.
+    """
+
+    def __init__(self, message: str | None = None):
+        self.message = "" if message is None else message
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        return self.message
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.message!r})"
+
+
+class BRSWarning(UserWarning):
+    """The base warning for boto3-refresh-session.
+
+    Parameters
+    ----------
+    message : str, optional
+        The message to raise.
+    """
+
+    def __init__(self, message: str | None = None):
+        self.message = "" if message is None else message
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        return self.message
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.message!r})"
+
+    @classmethod
+    def warn(cls, message: str, *, stacklevel: int = 2):
+        """Emits a BRSWarning with a consistent stacklevel."""
+
+        warnings.warn(cls(message), stacklevel=stacklevel)

boto3_refresh_session/methods/__init__.py

@@ -0,0 +1,10 @@
+__all__ = []
+
+from . import custom, iot, sts
+from .custom import *
+from .iot import *
+from .sts import *
+
+__all__.extend(custom.__all__)
+__all__.extend(iot.__all__)
+__all__.extend(sts.__all__)

boto3_refresh_session/methods/custom.py

@@ -0,0 +1,141 @@
+"""Custom refreshable session using a user-provided credential getter."""
+
+__all__ = ["CustomRefreshableSession"]
+
+from ..exceptions import BRSError, BRSWarning
+from ..utils import (
+    BaseRefreshableSession,
+    CustomCredentialsMethod,
+    CustomCredentialsMethodArgs,
+    Identity,
+    TemporaryCredentials,
+    refreshable_session,
+)
+
+
+@refreshable_session
+class CustomRefreshableSession(BaseRefreshableSession, registry_key="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: CustomCredentialsMethod
+        Required. Accepts a callable object that returns temporary AWS
+        security credentials. That object must return a dictionary containing
+        'access_key', 'secret_key', 'token', and 'expiry_time' when called.
+    custom_credentials_method_args : CustomCredentialsMethodArgs, 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``.
+    advisory_timeout : int, optional
+        USE THIS ARGUMENT WITH CAUTION!!!
+
+        Botocore will attempt to refresh credentials early according to
+        this value (in seconds), but will continue using the existing
+        credentials if refresh fails. Default is 15 minutes (900 seconds).
+    mandatory_timeout : int, optional
+        USE THIS ARGUMENT WITH CAUTION!!!
+
+        Botocore requires a successful refresh before continuing. If
+        refresh fails in this window (in seconds), API calls may fail.
+        Default is 10 minutes (600 seconds).
+    cache_clients : bool, optional
+        If ``True`` then clients created by this session will be cached and
+        reused for subsequent calls to :meth:`client()` with the same
+        parameter signatures. Due to the memory overhead of clients, the
+        default is ``True`` in order to protect system resources.
+
+    Other Parameters
+    ----------------
+    kwargs : dict
+        Optional keyword arguments for the :class:`boto3.session.Session`
+        object.
+
+    Examples
+    --------
+    Write (or import) the callable object 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 callable object to ``RefreshableSession``.
+
+    >>> sess = RefreshableSession(
+    >>>     method='custom',
+    >>>     custom_credentials_method=your_custom_credential_getter,
+    >>>     custom_credentials_method_args=...,
+    >>> )
+    """
+
+    def __init__(
+        self,
+        custom_credentials_method: CustomCredentialsMethod,
+        custom_credentials_method_args: (
+            CustomCredentialsMethodArgs | None
+        ) = None,
+        **kwargs,
+    ):
+        if "refresh_method" in kwargs:
+            BRSWarning.warn(
+                "'refresh_method' cannot be set manually. "
+                "Reverting to 'custom'."
+            )
+            del kwargs["refresh_method"]
+
+        # initializing BRSSession
+        super().__init__(refresh_method="custom", **kwargs)
+
+        # initializing various other attributes
+        self._custom_get_credentials: CustomCredentialsMethod = (
+            custom_credentials_method
+        )
+        self._custom_get_credentials_args: CustomCredentialsMethodArgs = (
+            custom_credentials_method_args
+            if custom_credentials_method_args is not None
+            else {}
+        )
+
+    def _get_credentials(self) -> TemporaryCredentials:
+        credentials: TemporaryCredentials = self._custom_get_credentials(
+            **self._custom_get_credentials_args
+        )
+        required_keys = {"access_key", "secret_key", "token", "expiry_time"}
+
+        if missing := required_keys - credentials.keys():
+            raise BRSError(
+                f"The dict returned by custom_credentials_method is missing "
+                "these key-value pairs: "
+                f"{', '.join(repr(param) for param in missing)}. "
+            )
+
+        return credentials
+
+    def get_identity(self) -> Identity:
+        """Returns metadata about the custom credential getter.
+
+        Returns
+        -------
+        Identity
+            Dict containing information about the custom credential getter.
+        """
+
+        source = getattr(
+            self._custom_get_credentials,
+            "__name__",
+            repr(self._custom_get_credentials),
+        )
+        return {"method": "custom", "source": repr(source)}

boto3_refresh_session/methods/iot/__init__.py

@@ -0,0 +1,7 @@
+__all__ = []
+
+from . import core
+from .core import IoTRefreshableSession
+from .x509 import IOTX509RefreshableSession
+
+__all__.extend(core.__all__)

boto3_refresh_session/methods/iot/core.py

@@ -0,0 +1,40 @@
+"""IoT refreshable session factory for selecting auth methods."""
+
+from __future__ import annotations
+
+__all__ = ["IoTRefreshableSession"]
+
+from typing import get_args
+
+from ...exceptions import BRSError
+from ...utils import (
+    BaseIoTRefreshableSession,
+    BaseRefreshableSession,
+    IoTAuthenticationMethod,
+)
+
+
+class IoTRefreshableSession(BaseRefreshableSession, registry_key="iot"):
+    def __new__(
+        cls,
+        authentication_method: IoTAuthenticationMethod = "x509",
+        **kwargs,
+    ) -> BaseIoTRefreshableSession:
+        if authentication_method not in (
+            methods := cls.get_available_authentication_methods()
+        ):
+            raise BRSError(
+                f"{authentication_method!r} is an invalid authentication "
+                "method parameter. Available authentication methods are "
+                f"{', '.join(repr(meth) for meth in methods)}."
+            )
+
+        return BaseIoTRefreshableSession.registry[authentication_method](
+            **kwargs
+        )
+
+    @classmethod
+    def get_available_authentication_methods(cls) -> list[str]:
+        args = list(get_args(IoTAuthenticationMethod))
+        args.remove("__iot_sentinel__")
+        return args