boto3-refresh-session 1.3.22__tar.gz → 2.0.1__tar.gz

{boto3_refresh_session-1.3.22 → boto3_refresh_session-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: boto3-refresh-session
-Version: 1.3.22
+Version: 2.0.1
 Summary: A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.
 License: MIT
 Keywords: boto3,botocore,aws,sts,ecs,credentials,token,refresh
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: boto3
 Requires-Dist: botocore
 Requires-Dist: requests
+Requires-Dist: typing-extensions
 Project-URL: Documentation, https://michaelthomasletts.github.io/boto3-refresh-session/index.html
 Project-URL: Repository, https://github.com/michaelthomasletts/boto3-refresh-session
 Description-Content-Type: text/markdown
@@ -57,7 +58,7 @@ Description-Content-Type: text/markdown
   </a>
 
   <a href="https://pepy.tech/projects/boto3-refresh-session">
-    <img src="https://img.shields.io/badge/downloads-76.9K-red?logo=python&color=%23FF0000&label=Downloads" alt="Downloads"/>
+    <img src="https://img.shields.io/badge/downloads-85.0K-red?logo=python&color=%23FF0000&label=Downloads" alt="Downloads"/>
   </a>
 
   <a href="https://michaelthomasletts.github.io/boto3-refresh-session/index.html">
@@ -83,6 +84,16 @@ Description-Content-Type: text/markdown
 
 </div>
 
+---
+
+## ⚠️ Important Update
+
+I am currently grappling with a serious medical condition that negatively impacts my vision. Accordingly, development of the `iot` and `ec2` modules has been delayed. Expect delayed responses to issues and pull requests until my health stabilizes. 
+
+Thank you for supporting this project. 
+
+---
+
 ## Features
 
 - Drop-in replacement for `boto3.session.Session`

{boto3_refresh_session-1.3.22 → boto3_refresh_session-2.0.1}/README.md

@@ -33,7 +33,7 @@
   </a>
 
   <a href="https://pepy.tech/projects/boto3-refresh-session">
-    <img src="https://img.shields.io/badge/downloads-76.9K-red?logo=python&color=%23FF0000&label=Downloads" alt="Downloads"/>
+    <img src="https://img.shields.io/badge/downloads-85.0K-red?logo=python&color=%23FF0000&label=Downloads" alt="Downloads"/>
   </a>
 
   <a href="https://michaelthomasletts.github.io/boto3-refresh-session/index.html">
@@ -59,6 +59,16 @@
 
 </div>
 
+---
+
+## ⚠️ Important Update
+
+I am currently grappling with a serious medical condition that negatively impacts my vision. Accordingly, development of the `iot` and `ec2` modules has been delayed. Expect delayed responses to issues and pull requests until my health stabilizes. 
+
+Thank you for supporting this project. 
+
+---
+
 ## Features
 
 - Drop-in replacement for `boto3.session.Session`

{boto3_refresh_session-1.3.22 → boto3_refresh_session-2.0.1}/boto3_refresh_session/__init__.py

@@ -1,10 +1,10 @@
-from .custom import CustomRefreshableSession
-from .ecs import ECSRefreshableSession
+from .methods.custom import CustomRefreshableSession
+from .methods.ecs import ECSRefreshableSession
+from .methods.sts import STSRefreshableSession
 from .session import RefreshableSession
-from .sts import STSRefreshableSession
 
 __all__ = ["RefreshableSession"]
-__version__ = "1.3.22"
+__version__ = "2.0.1"
 __title__ = "boto3-refresh-session"
 __author__ = "Mike Letts"
 __maintainer__ = "Mike Letts"

{boto3_refresh_session-1.3.22 → boto3_refresh_session-2.0.1}/boto3_refresh_session/exceptions.py

@@ -15,7 +15,7 @@ class BRSError(Exception):
         return self.message
 
     def __repr__(self) -> str:
-        return f"{self.__class__.__name__}({repr(self.message)})"
+        return f"{self.__class__.__name__}({self.message!r})"
 
 
 class BRSWarning(UserWarning):
@@ -35,4 +35,4 @@ 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})"

{boto3_refresh_session-1.3.22/boto3_refresh_session → boto3_refresh_session-2.0.1/boto3_refresh_session/methods}/custom.py

@@ -4,11 +4,12 @@ __all__ = ["CustomRefreshableSession"]
 
 from typing import Any, Callable
 
-from .exceptions import BRSError
-from .session import BaseRefreshableSession, TemporaryCredentials
+from ..exceptions import BRSError
+from ..session import BaseRefreshableSession
+from ..utils import TemporaryCredentials
 
 
-class CustomRefreshableSession(BaseRefreshableSession, method="custom"):
+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
@@ -74,7 +75,7 @@ class CustomRefreshableSession(BaseRefreshableSession, method="custom"):
             else {}
         )
 
-        self._refresh_using(
+        self.initialize(
             credentials_method=self._get_credentials,
             defer_refresh=defer_refresh is not False,
             refresh_method="custom",

{boto3_refresh_session-1.3.22/boto3_refresh_session → boto3_refresh_session-2.0.1/boto3_refresh_session/methods}/ecs.py

@@ -6,8 +6,9 @@ import os
 
 import requests
 
-from .exceptions import BRSError
-from .session import BaseRefreshableSession, TemporaryCredentials
+from ..exceptions import BRSError
+from ..session import BaseRefreshableSession
+from ..utils import TemporaryCredentials
 
 _ECS_CREDENTIALS_RELATIVE_URI = "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI"
 _ECS_CREDENTIALS_FULL_URI = "AWS_CONTAINER_CREDENTIALS_FULL_URI"
@@ -15,7 +16,7 @@ _ECS_AUTHORIZATION_TOKEN = "AWS_CONTAINER_AUTHORIZATION_TOKEN"
 _DEFAULT_ENDPOINT_BASE = "http://169.254.170.2"
 
 
-class ECSRefreshableSession(BaseRefreshableSession, method="ecs"):
+class ECSRefreshableSession(BaseRefreshableSession, registry_key="ecs"):
     """A boto3 session that automatically refreshes temporary AWS credentials
     from the ECS container credentials metadata endpoint.
 
@@ -40,7 +41,7 @@ class ECSRefreshableSession(BaseRefreshableSession, method="ecs"):
         self._headers = self._build_headers()
         self._http = self._init_http_session()
 
-        self._refresh_using(
+        self.initialize(
             credentials_method=self._get_credentials,
             defer_refresh=defer_refresh is not False,
             refresh_method="ecs-container-metadata",

boto3_refresh_session-2.0.1/boto3_refresh_session/methods/iot/__init__.typed

@@ -0,0 +1,4 @@
+from .certificate import IoTCertificateRefreshableSession
+from .core import IoTRefreshableSession
+
+__all__ = ["IoTRefreshableSession"]

boto3_refresh_session-2.0.1/boto3_refresh_session/methods/iot/certificate.typed

@@ -0,0 +1,54 @@
+__all__ = ["IoTCertificateRefreshableSession"]
+
+from pathlib import Path
+from typing import Any
+
+from ...exceptions import BRSError
+from ...utils import PKCS11, TemporaryCredentials
+from .core import BaseIoTRefreshableSession
+
+
+class IoTCertificateRefreshableSession(
+    BaseIoTRefreshableSession, registry_key="certificate"
+):
+    def __init__(
+        self,
+        endpoint: str,
+        role_alias: str,
+        thing_name: str,
+        certificate: str | bytes,
+        private_key: str | bytes | None = None,
+        pkcs11: PKCS11 | None = None,
+        ca: bytes | None = None,
+        verify_peer: bool = True,
+    ):
+        self.endpoint = endpoint
+        self.role_alias = role_alias
+        self.thing_name = thing_name
+        self.certificate = certificate
+        self.private_key = private_key
+        self.pkcs11 = pkcs11
+        self.ca = ca
+        self.verify_peer = verify_peer
+
+        if self.certificate and isinstance(self.certificate, str):
+            with open(Path(self.certificate), "rb") as cert_pem_file:
+                self.certificate = cert_pem_file.read()
+
+        if self.private_key is None and self.pkcs11 is None:
+            raise BRSError(
+                "Either 'private_key' or 'pkcs11' must be provided."
+            )
+
+        if self.private_key is not None and self.pkcs11 is not None:
+            raise BRSError(
+                "Only one of 'private_key' or 'pkcs11' can be provided."
+            )
+
+        if self.private_key and isinstance(self.private_key, str):
+            with open(Path(self.private_key), "rb") as private_key_pem_file:
+                self.private_key = private_key_pem_file.read()
+
+    def _get_credentials(self) -> TemporaryCredentials: ...
+
+    def get_identity(self) -> dict[str, Any]: ...

boto3_refresh_session-2.0.1/boto3_refresh_session/methods/iot/cognito.typed

@@ -0,0 +1,16 @@
+__all__ = ["IoTCognitoRefreshableSession"]
+
+from typing import Any
+
+from ...utils import TemporaryCredentials
+from .core import BaseIoTRefreshableSession
+
+
+class IoTCognitoRefreshableSession(
+    BaseIoTRefreshableSession, registry_key="cognito"
+):
+    def __init__(self): ...
+
+    def _get_credentials(self) -> TemporaryCredentials: ...
+
+    def get_identity(self) -> dict[str, Any]: ...

boto3_refresh_session-2.0.1/boto3_refresh_session/methods/iot/core.typed

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+__all__ = ["IoTRefreshableSession"]
+
+from typing import get_args
+
+from ...exceptions import BRSError
+from ...session import BaseRefreshableSession
+from ...utils import (
+    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",
+        **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

{boto3_refresh_session-1.3.22/boto3_refresh_session → boto3_refresh_session-2.0.1/boto3_refresh_session/methods}/sts.py

@@ -4,17 +4,18 @@ __all__ = ["STSRefreshableSession"]
 
 from typing import Any
 
-from .exceptions import BRSWarning
-from .session import BaseRefreshableSession, TemporaryCredentials
+from ..exceptions import BRSWarning
+from ..session import BaseRefreshableSession
+from ..utils import AssumeRoleParams, STSClientParams, TemporaryCredentials
 
 
-class STSRefreshableSession(BaseRefreshableSession, method="sts"):
+class STSRefreshableSession(BaseRefreshableSession, registry_key="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
+    assume_role_kwargs : AssumeRoleParams
         Required keyword arguments for :meth:`STS.Client.assume_role` (i.e.
         boto3 STS client).
     defer_refresh : bool, optional
@@ -22,7 +23,7 @@ class STSRefreshableSession(BaseRefreshableSession, method="sts"):
         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
+    sts_client_kwargs : STSClientParams, optional
         Optional keyword arguments for the :class:`STS.Client` object. Do not
         provide values for ``service_name`` as they are unnecessary. Default
         is None.
@@ -36,13 +37,12 @@ class STSRefreshableSession(BaseRefreshableSession, method="sts"):
 
     def __init__(
         self,
-        assume_role_kwargs: dict,
+        assume_role_kwargs: AssumeRoleParams,
         defer_refresh: bool | None = None,
-        sts_client_kwargs: dict | None = None,
+        sts_client_kwargs: STSClientParams | 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:
@@ -60,9 +60,9 @@ class STSRefreshableSession(BaseRefreshableSession, method="sts"):
             self._sts_client = self.client(service_name="sts")
 
         # mounting refreshable credentials
-        self._refresh_using(
+        self.initialize(
             credentials_method=self._get_credentials,
-            defer_refresh=defer_refresh,
+            defer_refresh=defer_refresh is not False,
             refresh_method="sts-assume-role",
         )
 

boto3_refresh_session-2.0.1/boto3_refresh_session/session.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+__all__ = ["RefreshableSession"]
+
+from typing import get_args
+
+from .exceptions import BRSError
+from .utils import BRSSession, CredentialProvider, Method, Registry
+
+
+class BaseRefreshableSession(
+    Registry[Method],
+    CredentialProvider,
+    BRSSession,
+    registry_key="__sentinel__",
+):
+    """Abstract base class for implementing refreshable AWS sessions.
+
+    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
+    ----------
+    registry : dict[str, type[BaseRefreshableSession]]
+        Class-level registry mapping method names to registered session types.
+    """
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+
+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.methods.custom.CustomRefreshableSession
+    boto3_refresh_session.methods.sts.STSRefreshableSession
+    boto3_refresh_session.methods.ecs.ECSRefreshableSession
+    """
+
+    def __new__(
+        cls, method: Method = "sts", **kwargs
+    ) -> BaseRefreshableSession:
+        if method not in (methods := cls.get_available_methods()):
+            raise BRSError(
+                f"{method!r} is an invalid method parameter. "
+                "Available methods are "
+                f"{', '.join(repr(meth) for meth in methods)}."
+            )
+
+        return BaseRefreshableSession.registry[method](**kwargs)
+
+    @classmethod
+    def get_available_methods(cls) -> list[str]:
+        """Lists all currently available credential refresh methods.
+
+        Returns
+        -------
+        list[str]
+            A list of all currently available credential refresh methods,
+            e.g. 'sts', 'ecs', 'custom'.
+        """
+
+        args = list(get_args(Method))
+        args.remove("__sentinel__")
+        return args

boto3_refresh_session-2.0.1/boto3_refresh_session/utils.py

@@ -0,0 +1,212 @@
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Generic,
+    List,
+    Literal,
+    TypedDict,
+    TypeVar,
+)
+
+from boto3.session import Session
+from botocore.credentials import (
+    DeferredRefreshableCredentials,
+    RefreshableCredentials,
+)
+
+from .exceptions import BRSWarning
+
+try:
+    from typing import NotRequired  # type: ignore[import]
+except ImportError:
+    from typing_extensions import NotRequired
+
+#: Type alias for all currently available IoT authentication methods.
+IoTAuthenticationMethod = Literal["certificate", "cognito", "__iot_sentinel__"]
+
+#: Type alias for all currently available credential refresh methods.
+Method = Literal[
+    "sts",
+    "ecs",
+    "custom",
+    "__sentinel__",
+]  # TODO: Add iot when implemented
+
+#: Type alias for all refresh method names.
+RefreshMethod = Literal[
+    "sts-assume-role",
+    "ecs-container-metadata",
+    "custom",
+]  # Add iot-certificate and iot-cognito when iot implemented
+
+#: Type alias for all currently registered credential refresh methods.
+RegistryKey = TypeVar("RegistryKey", bound=str)
+
+
+class Registry(Generic[RegistryKey]):
+    """Gives any hierarchy a class-level registry."""
+
+    registry: ClassVar[dict[str, type]] = {}
+
+    def __init_subclass__(cls, *, registry_key: RegistryKey, **kwargs: Any):
+        super().__init_subclass__(**kwargs)
+
+        if registry_key in cls.registry:
+            BRSWarning(f"{registry_key!r} already registered. Overwriting.")
+
+        if "sentinel" not in registry_key:
+            cls.registry[registry_key] = cls
+
+    @classmethod
+    def items(cls) -> dict[str, type]:
+        """Typed accessor for introspection / debugging."""
+
+        return dict(cls.registry)
+
+
+class TemporaryCredentials(TypedDict):
+    """Temporary IAM credentials."""
+
+    access_key: str
+    secret_key: str
+    token: str
+    expiry_time: datetime | str
+
+
+class RefreshableTemporaryCredentials(TypedDict):
+    """Refreshable IAM credentials.
+
+    Parameters
+    ----------
+    AWS_ACCESS_KEY_ID : str
+        AWS access key identifier.
+    AWS_SECRET_ACCESS_KEY : str
+        AWS secret access key.
+    AWS_SESSION_TOKEN : str
+        AWS session token.
+    """
+
+    AWS_ACCESS_KEY_ID: str
+    AWS_SECRET_ACCESS_KEY: str
+    AWS_SESSION_TOKEN: str
+
+
+class CredentialProvider(ABC):
+    """Defines the abstract surface every refreshable session must expose."""
+
+    @abstractmethod
+    def _get_credentials(self) -> TemporaryCredentials: ...
+
+    @abstractmethod
+    def get_identity(self) -> dict[str, Any]: ...
+
+
+class BRSSession(Session):
+    """Wrapper for boto3.session.Session.
+
+    Other Parameters
+    ----------------
+    kwargs : Any
+        Optional keyword arguments for initializing boto3.session.Session."""
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+    def initialize(
+        self,
+        credentials_method: Callable,
+        defer_refresh: bool,
+        refresh_method: RefreshMethod,
+    ):
+        # determining how exactly to refresh expired temporary credentials
+        if not defer_refresh:
+            self._credentials = RefreshableCredentials.create_from_metadata(
+                metadata=credentials_method(),
+                refresh_using=credentials_method,
+                method=refresh_method,
+            )
+        else:
+            self._credentials = DeferredRefreshableCredentials(
+                refresh_using=credentials_method, method=refresh_method
+            )
+
+    def refreshable_credentials(self) -> RefreshableTemporaryCredentials:
+        """The current temporary AWS security credentials.
+
+        Returns
+        -------
+        RefreshableTemporaryCredentials
+            Temporary AWS security credentials containing:
+                AWS_ACCESS_KEY_ID : str
+                    AWS access key identifier.
+                AWS_SECRET_ACCESS_KEY : str
+                    AWS secret access key.
+                AWS_SESSION_TOKEN : str
+                    AWS session token.
+        """
+
+        creds = self.get_credentials().get_frozen_credentials()
+        return {
+            "AWS_ACCESS_KEY_ID": creds.access_key,
+            "AWS_SECRET_ACCESS_KEY": creds.secret_key,
+            "AWS_SESSION_TOKEN": creds.token,
+        }
+
+    @property
+    def credentials(self) -> RefreshableTemporaryCredentials:
+        """The current temporary AWS security credentials."""
+
+        return self.refreshable_credentials()
+
+
+class Tag(TypedDict):
+    Key: str
+    Value: str
+
+
+class PolicyDescriptorType(TypedDict):
+    arn: str
+
+
+class ProvidedContext(TypedDict):
+    ProviderArn: str
+    ContextAssertion: str
+
+
+class AssumeRoleParams(TypedDict):
+    RoleArn: str
+    RoleSessionName: str
+    PolicyArns: NotRequired[List[PolicyDescriptorType]]
+    Policy: NotRequired[str]
+    DurationSeconds: NotRequired[int]
+    ExternalId: NotRequired[str]
+    SerialNumber: NotRequired[str]
+    TokenCode: NotRequired[str]
+    Tags: NotRequired[List[Tag]]
+    TransitiveTagKeys: NotRequired[List[str]]
+    SourceIdentity: NotRequired[str]
+    ProvidedContexts: NotRequired[List[ProvidedContext]]
+
+
+class STSClientParams(TypedDict):
+    region_name: NotRequired[str]
+    api_version: NotRequired[str]
+    use_ssl: NotRequired[bool]
+    verify: NotRequired[bool | str]
+    endpoint_url: NotRequired[str]
+    aws_access_key_id: NotRequired[str]
+    aws_secret_access_key: NotRequired[str]
+    aws_session_token: NotRequired[str]
+    config: NotRequired[Any]
+    aws_account_id: NotRequired[str]
+
+
+class PKCS11(TypedDict):
+    pkcs11_loc: str
+    user_pin: NotRequired[str]
+    slot_id: NotRequired[int]
+    token_label: NotRequired[str | None]
+    private_key_label: NotRequired[str | None]

{boto3_refresh_session-1.3.22 → boto3_refresh_session-2.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "boto3-refresh-session"
-version = "1.3.22"
+version = "2.0.1"
 description = "A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically."
 authors = [
     {name = "Mike Letts",email = "lettsmt@gmail.com"}
@@ -8,7 +8,7 @@ authors = [
 license = {text = "MIT"}
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = ["boto3", "botocore", "requests"]
+dependencies = ["boto3", "botocore", "requests", "typing-extensions"]
 keywords = ["boto3", "botocore", "aws", "sts", "ecs", "credentials", "token", "refresh"]
 maintainers = [
   {name="Michael Letts", email="lettsmt@gmail.com"},
@@ -37,6 +37,7 @@ numpydoc = "^1.8.0"
 tomlkit = "^0.13.2"
 jinja2 = "^3.1.6"
 flask = "^3.1.1"
+pepy-chart = {git = "https://github.com/michaelthomasletts/pepy-chart.git"}
 
 [tool.black]
 line-length = 79

boto3_refresh_session-1.3.22/boto3_refresh_session/session.py

@@ -1,175 +0,0 @@
-from __future__ import annotations
-
-__all__ = ["RefreshableSession"]
-
-from abc import ABC, abstractmethod
-from datetime import datetime
-from typing import Any, Callable, ClassVar, Literal, TypedDict, get_args
-
-from boto3.session import Session
-from botocore.credentials import (
-    DeferredRefreshableCredentials,
-    RefreshableCredentials,
-)
-
-from .exceptions import BRSError, BRSWarning
-
-#: Type alias for all currently available credential refresh methods.
-Method = Literal["sts", "ecs", "custom"]
-RefreshMethod = Literal["sts-assume-role", "ecs-container-metadata", "custom"]
-
-
-class TemporaryCredentials(TypedDict):
-    """Temporary IAM credentials."""
-
-    access_key: str
-    secret_key: str
-    token: str
-    expiry_time: datetime | str
-
-
-class BaseRefreshableSession(ABC, Session):
-    """Abstract base class for implementing refreshable AWS sessions.
-
-    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
-    ----------
-    registry : dict[str, type[BaseRefreshableSession]]
-        Class-level registry mapping method names to registered session types.
-    """
-
-    # adding this and __init_subclass__ to avoid circular imports
-    # as well as simplify future addition of new methods
-    registry: ClassVar[dict[Method, type[BaseRefreshableSession]]] = {}
-
-    def __init_subclass__(cls, method: Method):
-        super().__init_subclass__()
-
-        # guarantees that methods are unique
-        if method in BaseRefreshableSession.registry:
-            BRSWarning(
-                f"Method {repr(method)} is already registered. Overwriting."
-            )
-
-        BaseRefreshableSession.registry[method] = cls
-
-    def __init__(self, **kwargs):
-        super().__init__(**kwargs)
-
-    @abstractmethod
-    def _get_credentials(self) -> TemporaryCredentials: ...
-
-    @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._credentials = RefreshableCredentials.create_from_metadata(
-                metadata=credentials_method(),
-                refresh_using=credentials_method,
-                method=refresh_method,
-            )
-        else:
-            self._credentials = DeferredRefreshableCredentials(
-                refresh_using=credentials_method, method=refresh_method
-            )
-
-    def refreshable_credentials(self) -> dict[str, str]:
-        """The current temporary AWS security credentials.
-
-        Returns
-        -------
-        dict[str, str]
-            Temporary AWS security credentials containing:
-                AWS_ACCESS_KEY_ID : str
-                    AWS access key identifier.
-                AWS_SECRET_ACCESS_KEY : str
-                    AWS secret access key.
-                AWS_SESSION_TOKEN : str
-                    AWS session token.
-        """
-
-        creds = self.get_credentials().get_frozen_credentials()
-        return {
-            "AWS_ACCESS_KEY_ID": creds.access_key,
-            "AWS_SECRET_ACCESS_KEY": creds.secret_key,
-            "AWS_SESSION_TOKEN": creds.token,
-        }
-
-    @property
-    def credentials(self) -> dict[str, str]:
-        """The current temporary AWS security credentials."""
-
-        return self.refreshable_credentials()
-
-
-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.custom.CustomRefreshableSession
-    boto3_refresh_session.sts.STSRefreshableSession
-    boto3_refresh_session.ecs.ECSRefreshableSession
-    """
-
-    def __new__(
-        cls, method: Method = "sts", **kwargs
-    ) -> BaseRefreshableSession:
-        if method not in (methods := cls.get_available_methods()):
-            raise BRSError(
-                f"{repr(method)} is an invalid method parameter. "
-                "Available methods are "
-                f"{', '.join(repr(meth) for meth in methods)}."
-            )
-
-        obj = BaseRefreshableSession.registry[method]
-        return obj(**kwargs)
-
-    @classmethod
-    def get_available_methods(cls) -> list[str]:
-        """Lists all currently available credential refresh methods.
-
-        Returns
-        -------
-        list[str]
-            A list of all currently available credential refresh methods,
-            e.g. 'sts'.
-        """
-
-        return list(get_args(Method))