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

boto3_refresh_session/__init__.py

@@ -1,9 +1,21 @@
-from .session import RefreshableSession
+# 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__ = "2.0.5"
+__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__ = "MIT"
+__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__}({self.message!r})"
+        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):
@@ -36,3 +142,9 @@ class BRSWarning(UserWarning):
 
     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,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

@@ -1,14 +1,23 @@
-from __future__ import annotations
+# 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__ = ["CustomRefreshableSession"]
+"""Custom refreshable session using a user-provided credential getter."""
 
-from typing import Any, Callable
+__all__ = ["CustomRefreshableSession"]
 
-from ..exceptions import BRSError
-from ..session import BaseRefreshableSession
-from ..utils import TemporaryCredentials
+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
@@ -17,11 +26,11 @@ class CustomRefreshableSession(BaseRefreshableSession, registry_key="custom"):
 
     Parameters
     ----------
-    custom_credentials_method: Callable
+    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 : dict[str, Any], optional
+    custom_credentials_method_args : CustomCredentialsMethodArgs, optional
         Optional keyword arguments for the function passed to the
         ``custom_credentials_method`` parameter.
     defer_refresh : bool, optional
@@ -29,6 +38,23 @@ class CustomRefreshableSession(BaseRefreshableSession, registry_key="custom"):
         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
     ----------------
@@ -61,26 +87,32 @@ class CustomRefreshableSession(BaseRefreshableSession, registry_key="custom"):
 
     def __init__(
         self,
-        custom_credentials_method: Callable,
-        custom_credentials_method_args: dict[str, Any] | None = None,
-        defer_refresh: bool | None = None,
+        custom_credentials_method: CustomCredentialsMethod,
+        custom_credentials_method_args: (
+            CustomCredentialsMethodArgs | None
+        ) = None,
         **kwargs,
     ):
-        super().__init__(**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)
 
-        self._custom_get_credentials = custom_credentials_method
-        self._custom_get_credentials_args = (
+        # 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 {}
         )
 
-        self.initialize(
-            credentials_method=self._get_credentials,
-            defer_refresh=defer_refresh is not False,
-            refresh_method="custom",
-        )
-
     def _get_credentials(self) -> TemporaryCredentials:
         credentials: TemporaryCredentials = self._custom_get_credentials(
             **self._custom_get_credentials_args
@@ -88,20 +120,20 @@ class CustomRefreshableSession(BaseRefreshableSession, registry_key="custom"):
         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)}. "
+            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) -> dict[str, str]:
+    def get_identity(self) -> Identity:
         """Returns metadata about the custom credential getter.
 
         Returns
         -------
-        dict[str, str]
+        Identity
             Dict containing information about the custom credential getter.
         """
 

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.typed → core.py}

@@ -1,42 +1,38 @@
+# 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 BRSError
-from ...session import BaseRefreshableSession
+from ...exceptions import BRSValidationError
 from ...utils import (
+    BaseIoTRefreshableSession,
+    BaseRefreshableSession,
     IoTAuthenticationMethod,
-    BRSSession,
-    CredentialProvider,
-    Registry,
 )
 
 
-class BaseIoTRefreshableSession(
-    Registry[IoTAuthenticationMethod],
-    CredentialProvider,
-    BRSSession,
-    registry_key="__iot_sentinel__",
-):
-    def __init__(self, **kwargs):
-        super().__init__(**kwargs)
-
-
 class IoTRefreshableSession(BaseRefreshableSession, registry_key="iot"):
     def __new__(
         cls,
-        authentication_method: IoTAuthenticationMethod = "certificate",
+        authentication_method: IoTAuthenticationMethod = "x509",
         **kwargs,
     ) -> BaseIoTRefreshableSession:
         if authentication_method not in (
             methods := cls.get_available_authentication_methods()
         ):
-            raise BRSError(
+            raise BRSValidationError(
                 f"{authentication_method!r} is an invalid authentication "
                 "method parameter. Available authentication methods are "
-                f"{', '.join(repr(meth) for meth in methods)}."
+                f"{', '.join(repr(meth) for meth in methods)}.",
+                param="authentication_method",
+                value=authentication_method,
             )
 
         return BaseIoTRefreshableSession.registry[authentication_method](