boto3-refresh-session 1.3.11__py3-none-any.whl → 7.0.1__py3-none-any.whl

boto3_refresh_session/__init__.py

@@ -1,8 +1,21 @@
-from .custom import CustomRefreshableSession
-from .ecs import ECSRefreshableSession
-from .session import RefreshableSession
-from .sts import STSRefreshableSession
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
-__all__ = ["RefreshableSession"]
-__version__ = "1.3.11"
+__all__ = []
+
+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__)
+__all__.extend(exceptions.__all__)
+__version__ = "7.0.1"
+__title__ = "boto3-refresh-session"
 __author__ = "Mike Letts"
+__maintainer__ = "Mike Letts"
+__license__ = "MPL-2.0"
+__email__ = "lettsmt@gmail.com"

boto3_refresh_session/exceptions.py

@@ -1,3 +1,26 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Custom exception and warning types for boto3-refresh-session."""
+
+__all__ = [
+    "BRSError",
+    "BRSValidationError",
+    "BRSConfigurationError",
+    "BRSCredentialError",
+    "BRSConnectionError",
+    "BRSRequestError",
+    "BRSCacheError",
+    "BRSCacheNotFoundError",
+    "BRSCacheExistsError",
+    "BRSWarning",
+]
+
+import warnings
+from typing import Any
+
+
 class BRSError(Exception):
     """The base exception for boto3-refresh-session.
 
@@ -5,17 +28,100 @@ class BRSError(Exception):
     ----------
     message : str, optional
         The message to raise.
+    code : str | int, optional
+        A short machine-friendly code for the error.
+    status_code : int, optional
+        An HTTP status code, if applicable.
+    details : dict[str, Any], optional
+        Extra structured metadata for debugging or logging.
+    param : str, optional
+        The parameter name related to the error.
+    value : Any, optional
+        The parameter value related to the error.
     """
 
-    def __init__(self, message: str | None = None):
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        code: str | int | None = None,
+        status_code: int | None = None,
+        details: dict[str, Any] | None = None,
+        param: str | None = None,
+        value: Any | None = None,
+    ):
         self.message = "" if message is None else message
+        self.code = code
+        self.status_code = status_code
+        self.details = details
+        self.param = param
+        self.value = value
         super().__init__(self.message)
 
     def __str__(self) -> str:
-        return self.message
+        base = self.message
+        extras: list[str] = []
+        if self.code is not None:
+            extras.append(f"code={self.code!r}")
+        if self.status_code is not None:
+            extras.append(f"status_code={self.status_code!r}")
+        if self.param is not None:
+            extras.append(f"param={self.param!r}")
+        if self.value is not None:
+            extras.append(f"value={self.value!r}")
+        if self.details is not None:
+            extras.append(f"details={self.details!r}")
+        if extras:
+            if base:
+                return f"{base} ({', '.join(extras)})"
+            return ", ".join(extras)
+        return base
 
     def __repr__(self) -> str:
-        return f"{self.__class__.__name__}({repr(self.message)})"
+        args = [repr(self.message)]
+        if self.code is not None:
+            args.append(f"code={self.code!r}")
+        if self.status_code is not None:
+            args.append(f"status_code={self.status_code!r}")
+        if self.param is not None:
+            args.append(f"param={self.param!r}")
+        if self.value is not None:
+            args.append(f"value={self.value!r}")
+        if self.details is not None:
+            args.append(f"details={self.details!r}")
+        return f"{self.__class__.__name__}({', '.join(args)})"
+
+
+class BRSValidationError(BRSError):
+    """Raised when inputs are missing or invalid."""
+
+
+class BRSConfigurationError(BRSError):
+    """Raised when configuration is incompatible or malformed."""
+
+
+class BRSCredentialError(BRSError):
+    """Raised when credential data is malformed or incomplete."""
+
+
+class BRSConnectionError(BRSError):
+    """Raised when a connection or transport fails."""
+
+
+class BRSRequestError(BRSError):
+    """Raised when a remote request fails."""
+
+
+class BRSCacheError(BRSError):
+    """Raised when cache operations violate the cache contract."""
+
+
+class BRSCacheNotFoundError(BRSCacheError):
+    """Raised when a cached item is not found."""
+
+
+class BRSCacheExistsError(BRSCacheError):
+    """Raised when attempting to insert an existing cached item."""
 
 
 class BRSWarning(UserWarning):
@@ -35,4 +141,10 @@ class BRSWarning(UserWarning):
         return self.message
 
     def __repr__(self) -> str:
-        return f"{self.__class__.__name__}({repr(self.message)})"
+        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,14 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+__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,145 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Custom refreshable session using a user-provided credential getter."""
+
+__all__ = ["CustomRefreshableSession"]
+
+from ..exceptions import BRSCredentialError, 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 BRSCredentialError(
+                "The dict returned by custom_credentials_method is missing "
+                "required key-value pairs.",
+                details={"missing": sorted(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,11 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+__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,46 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""IoT refreshable session factory for selecting auth methods."""
+
+from __future__ import annotations
+
+__all__ = ["IoTRefreshableSession"]
+
+from typing import get_args
+
+from ...exceptions import BRSValidationError
+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 BRSValidationError(
+                f"{authentication_method!r} is an invalid authentication "
+                "method parameter. Available authentication methods are "
+                f"{', '.join(repr(meth) for meth in methods)}.",
+                param="authentication_method",
+                value=authentication_method,
+            )
+
+        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