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

boto3_refresh_session/__init__.py

@@ -13,7 +13,7 @@ from .session import *
 
 __all__.extend(session.__all__)
 __all__.extend(exceptions.__all__)
-__version__ = "7.0.1"
+__version__ = "7.1.3"
 __title__ = "boto3-refresh-session"
 __author__ = "Mike Letts"
 __maintainer__ = "Mike Letts"

boto3_refresh_session/exceptions.py

@@ -5,15 +5,15 @@
 """Custom exception and warning types for boto3-refresh-session."""
 
 __all__ = [
-    "BRSError",
-    "BRSValidationError",
+    "BRSCacheError",
+    "BRSCacheExistsError",
+    "BRSCacheNotFoundError",
     "BRSConfigurationError",
-    "BRSCredentialError",
     "BRSConnectionError",
+    "BRSCredentialError",
+    "BRSError",
     "BRSRequestError",
-    "BRSCacheError",
-    "BRSCacheNotFoundError",
-    "BRSCacheExistsError",
+    "BRSValidationError",
     "BRSWarning",
 ]
 

boto3_refresh_session/methods/sts.py

@@ -10,12 +10,11 @@ from typing import Callable
 
 from ..exceptions import BRSConfigurationError, BRSValidationError, BRSWarning
 from ..utils import (
-    MFA_SERIAL_PATTERN,
-    ROLE_ARN_PATTERN,
-    ROLE_SESSION_NAME_PATTERN,
+    AssumeRoleConfig,
     AssumeRoleParams,
     BaseRefreshableSession,
     Identity,
+    STSClientConfig,
     STSClientParams,
     TemporaryCredentials,
     refreshable_session,
@@ -29,7 +28,7 @@ class STSRefreshableSession(BaseRefreshableSession, registry_key="sts"):
 
     Parameters
     ----------
-    assume_role_kwargs : AssumeRoleParams
+    assume_role_kwargs : AssumeRoleParams | AssumeRoleConfig
         Required keyword arguments for :meth:`STS.Client.assume_role` (i.e.
         boto3 STS client). ``RoleArn`` is required. ``RoleSessionName`` will
         default to 'boto3-refresh-session' if not provided.
@@ -45,7 +44,7 @@ class STSRefreshableSession(BaseRefreshableSession, registry_key="sts"):
            ``TokenCode`` in ``assume_role_kwargs``. You are responsible for
            updating ``assume_role_kwargs["TokenCode"]`` before the token
            expires.
-    sts_client_kwargs : STSClientParams, optional
+    sts_client_kwargs : STSClientParams | STSClientConfig, optional
         Optional keyword arguments for the :class:`STS.Client` object. Do not
         provide values for ``service_name`` as they are unnecessary. Default
         is None.
@@ -86,16 +85,39 @@ class STSRefreshableSession(BaseRefreshableSession, registry_key="sts"):
     kwargs : dict
         Optional keyword arguments for the :class:`boto3.session.Session`
         object.
+
+    See Also
+    --------
+    boto3_refresh_session.utils.config.config.AssumeRoleConfig
+    boto3_refresh_session.utils.config.config.STSClientConfig
     """
 
     def __init__(
         self,
-        assume_role_kwargs: AssumeRoleParams,
-        sts_client_kwargs: STSClientParams | None = None,
+        assume_role_kwargs: AssumeRoleParams | AssumeRoleConfig,
+        sts_client_kwargs: STSClientParams | STSClientConfig | None = None,
         mfa_token_provider: Callable[[], str] | None = None,
         mfa_token_provider_kwargs: dict | None = None,
         **kwargs,
     ):
+        # initializing asssume_role_kwargs attribute
+        match assume_role_kwargs:
+            case AssumeRoleConfig():
+                self.assume_role_kwargs = assume_role_kwargs
+            case _:
+                self.assume_role_kwargs = AssumeRoleConfig(
+                    **assume_role_kwargs
+                )
+
+        # initializing sts_client_kwargs attribute
+        match sts_client_kwargs:
+            case STSClientConfig():
+                self.sts_client_kwargs = sts_client_kwargs
+            case None:
+                self.sts_client_kwargs = STSClientConfig()
+            case _:
+                self.sts_client_kwargs = STSClientConfig(**sts_client_kwargs)
+
         # ensuring 'refresh_method' is not set manually
         if "refresh_method" in kwargs:
             BRSWarning.warn(
@@ -104,43 +126,10 @@ class STSRefreshableSession(BaseRefreshableSession, registry_key="sts"):
             )
             del kwargs["refresh_method"]
 
-        # verifying 'RoleArn' is provided in 'assume_role_kwargs'
-        if "RoleArn" not in assume_role_kwargs:
-            raise BRSConfigurationError(
-                "'RoleArn' must be provided in 'assume_role_kwargs'!",
-                param="RoleArn",
-            )
-
-        # verifying 'RoleArn' format
-        if not ROLE_ARN_PATTERN.match(assume_role_kwargs["RoleArn"]):
-            raise BRSValidationError(
-                "'RoleArn' in 'assume_role_kwargs' is not a valid AWS "
-                "Role ARN!",
-                param="RoleArn",
-                value=assume_role_kwargs.get("RoleArn"),
-            )
-
-        # setting default 'RoleSessionName' if not provided
-        if "RoleSessionName" not in assume_role_kwargs:
-            BRSWarning.warn(
-                "'RoleSessionName' not provided in "
-                "'assume_role_kwargs'! Defaulting to "
-                "'boto3-refresh-session'."
-            )
-            assume_role_kwargs["RoleSessionName"] = "boto3-refresh-session"
-
-        # verifying 'RoleSessionName' format
-        if not ROLE_SESSION_NAME_PATTERN.match(
-            assume_role_kwargs["RoleSessionName"]
-        ):
-            raise BRSValidationError(
-                "'RoleSessionName' in 'assume_role_kwargs' is not valid! "
-                "It must be 2-64 characters long and can contain only "
-                "alphanumeric characters and the following symbols: "
-                "'+=,.@-'.",
-                param="RoleSessionName",
-                value=assume_role_kwargs.get("RoleSessionName"),
-            )
+        # setting 'RoleSessionName' if not provided
+        self.assume_role_kwargs.RoleSessionName = self.assume_role_kwargs.get(
+            "RoleSessionName", "boto3-refresh-session"
+        )
 
         # store MFA token provider
         try:
@@ -158,26 +147,12 @@ class STSRefreshableSession(BaseRefreshableSession, registry_key="sts"):
             ) from err
 
         # storing mfa_token_provider_kwargs
-        self.mfa_token_provider_kwargs = (
-            mfa_token_provider_kwargs if mfa_token_provider_kwargs else {}
-        )
-
-        # verifying 'SerialNumber' format if provided
-        if "SerialNumber" in assume_role_kwargs:
-            if not MFA_SERIAL_PATTERN.match(
-                assume_role_kwargs["SerialNumber"]
-            ):
-                raise BRSValidationError(
-                    "'SerialNumber' in 'assume_role_kwargs' is not a valid "
-                    "AWS MFA device ARN!",
-                    param="SerialNumber",
-                    value=assume_role_kwargs.get("SerialNumber"),
-                )
+        self.mfa_token_provider_kwargs = mfa_token_provider_kwargs or {}
 
         # ensure SerialNumber is set appropriately with mfa_token_provider
         if (
             self.mfa_token_provider
-            and "SerialNumber" not in assume_role_kwargs
+            and self.assume_role_kwargs.SerialNumber is None
         ):
             raise BRSConfigurationError(
                 "'SerialNumber' must be provided in 'assume_role_kwargs' "
@@ -185,77 +160,53 @@ class STSRefreshableSession(BaseRefreshableSession, registry_key="sts"):
                 param="SerialNumber",
             )
 
-        # ensure SerialNumber and TokenCode are set without mfa_token_provider
+        # ensure SerialNumber and TokenCode are set in the absence of
+        # mfa_token_provider
         if (
             self.mfa_token_provider is None
             and (
-                "SerialNumber" in assume_role_kwargs
-                and "TokenCode" not in assume_role_kwargs
+                self.assume_role_kwargs.SerialNumber is not None
+                and self.assume_role_kwargs.TokenCode is None
             )
             or (
-                "SerialNumber" not in assume_role_kwargs
-                and "TokenCode" in assume_role_kwargs
+                self.assume_role_kwargs.SerialNumber is None
+                and self.assume_role_kwargs.TokenCode is not None
             )
         ):
             raise BRSConfigurationError(
                 "'SerialNumber' and 'TokenCode' must be provided in "
-                "'assume_role_kwargs' when 'mfa_token_provider' is not set!",
+                "'assume_role_kwargs' when 'mfa_token_provider' is not set "
+                "and 'SerialNumber' or 'TokenCode' is missing!",
                 param="SerialNumber/TokenCode",
             )
 
         # warn if TokenCode provided with mfa_token_provider
-        if self.mfa_token_provider and "TokenCode" in assume_role_kwargs:
+        if (
+            self.mfa_token_provider
+            and self.assume_role_kwargs.TokenCode is not None
+        ):
             BRSWarning.warn(
                 "'TokenCode' provided in 'assume_role_kwargs' will be "
                 "ignored and overridden by 'mfa_token_provider' on each "
                 "refresh."
             )
 
-        # initializing assume role kwargs attribute
-        self.assume_role_kwargs = assume_role_kwargs
-
         # initializing BRSSession
         super().__init__(refresh_method="sts-assume-role", **kwargs)
 
-        if sts_client_kwargs is not None:
-            # overwriting 'service_name' if if appears in sts_client_kwargs
-            if "service_name" in sts_client_kwargs:
-                BRSWarning.warn(
-                    "'sts_client_kwargs' cannot contain values for "
-                    "'service_name'. Reverting to service_name = 'sts'."
-                )
-                del sts_client_kwargs["service_name"]
-            self._sts_client = self.client(
-                service_name="sts", **sts_client_kwargs
-            )
-        else:
-            self._sts_client = self.client(service_name="sts")
+        # initializing STS client attribute
+        self._sts_client = self.client(**self.sts_client_kwargs)
 
     def _get_credentials(self) -> TemporaryCredentials:
-        params = dict(self.assume_role_kwargs)
-
         # override TokenCode with fresh token from provider if configured
-        if self.mfa_token_provider:
-            params["TokenCode"] = self.mfa_token_provider(
+        if self.mfa_token_provider is not None:
+            self.assume_role_kwargs.TokenCode = self.mfa_token_provider(
                 **self.mfa_token_provider_kwargs
             )
 
-        # validating TokenCode format
-        if (token_code := params.get("TokenCode")) is not None:
-            if (
-                not isinstance(token_code, str)
-                or len(token_code) != 6
-                or not token_code.isdigit()
-            ):
-                raise BRSValidationError(
-                    "'TokenCode' must be a 6-digit string per AWS MFA "
-                    "token specifications!",
-                    param="TokenCode",
-                )
-
-        temporary_credentials = self._sts_client.assume_role(**params)[
-            "Credentials"
-        ]
+        temporary_credentials = self._sts_client.assume_role(
+            **self.assume_role_kwargs
+        )["Credentials"]
 
         return {
             "access_key": temporary_credentials.get("AccessKeyId"),

boto3_refresh_session/session.py

@@ -66,6 +66,18 @@ class RefreshableSession:
     boto3_refresh_session.methods.custom.CustomRefreshableSession
     boto3_refresh_session.methods.iot.x509.IOTX509RefreshableSession
     boto3_refresh_session.methods.sts.STSRefreshableSession
+
+    Examples
+    --------
+
+    Basic initialization using STS AssumeRole (i.e. ``method="sts"``):
+
+    >>> from boto3_refresh_session import AssumeRoleConfig, RefreshableSession
+    >>> session = RefreshableSession(
+    ...     AssumeRoleConfig(RoleArn="<your-role-arn>"),
+    ...     region_name="us-east-1"
+    ... )
+    >>> s3 = session.client("s3")
     """
 
     def __new__(

boto3_refresh_session/utils/__init__.py

@@ -4,13 +4,15 @@
 
 __all__ = []
 
-from . import cache, constants, internal, typing
+from . import cache, config, constants, internal, typing
 from .cache import *
+from .config import *
 from .constants import *
 from .internal import *
 from .typing import *
 
 __all__.extend(cache.__all__)
+__all__.extend(config.__all__)
 __all__.extend(constants.__all__)
 __all__.extend(internal.__all__)
 __all__.extend(typing.__all__)

boto3_refresh_session/utils/config/__init__.py

@@ -0,0 +1,10 @@
+# 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 config
+from .config import *
+
+__all__.extend(config.__all__)

boto3_refresh_session/utils/config/config.py

@@ -0,0 +1,274 @@
+# 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/.
+
+"""Configurations for AWS STS AssumeRole and STS Client.
+
+The following configuration classes do not validate most user inputs except
+'TokenCode' in `AssumeRoleConfig` and `service_name` in `STSClientConfig`.
+It is the user's responsibility to ensure that the provided values conform
+to AWS and boto specifications. The purpose of these configurations is to
+provide a structured way to manage parameters when working with AWS STS.
+
+For additional information on AWS specifications, refer to the
+`API Reference for AssumeRole <https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html>`_.
+"""
+
+__all__ = ["AssumeRoleConfig", "STSClientConfig"]
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from botocore.config import Config
+
+from ...exceptions import BRSValidationError, BRSWarning
+from ..constants import (
+    ASSUME_ROLE_CONFIG_PARAMETERS,
+    STS_CLIENT_CONFIG_PARAMETERS,
+)
+from ..typing import PolicyDescriptorType, ProvidedContext, Tag
+
+
+class BaseConfig(dict, ABC):
+    """Base configuration class."""
+
+    def __init__(self, **kwargs):
+        super().__init__()
+        self.update(kwargs)
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self._validate(key, value)
+        if value is None:
+            if key in self:
+                super().__delitem__(key)
+            return
+        super().__setitem__(key, value)
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError:
+            try:
+                self._validate(name, None)
+            except BRSValidationError as exc:
+                raise AttributeError(
+                    f"'{name}' is an unknown attribute."
+                ) from exc
+            return None
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        self.__setitem__(name, value)
+
+    def update(self, *args, **kwargs) -> None:
+        for key, value in dict(*args, **kwargs).items():
+            self.__setitem__(key, value)
+
+    def setdefault(self, key: str, default: Any = None):
+        if key in self:
+            return super().setdefault(key, default)
+        self._validate(key, default)
+        return super().setdefault(key, default)
+
+    @abstractmethod
+    def _validate(self, key: str, value: Any) -> None: ...
+
+
+class AssumeRoleConfig(BaseConfig):
+    """Configuration for AWS STS AssumeRole API.
+
+    Attributes
+    ----------
+    RoleArn : str
+        The Amazon Resource Name (ARN) of the role to assume.
+    RoleSessionName : str, optional
+        An identifier for the assumed role session.
+    PolicyArns : list of PolicyDescriptorType, optional
+        The Amazon Resource Names (ARNs) of the IAM managed policies to
+        use as managed session policies.
+    Policy : str, optional
+        An IAM policy in JSON format to use as an inline session policy.
+    DurationSeconds : int, optional
+        The duration, in seconds, of the role session.
+    ExternalId : str, optional
+        A unique identifier that might be required when you assume a role
+        in another account.
+    SerialNumber : str, optional
+        The identification number of the MFA device.
+    TokenCode : str, optional
+        The value provided by the MFA device. Must be a 6-digit numeric
+        string.
+    Tags : list of Tag, optional
+        A list of session tags.
+    TransitiveTagKeys : list of str, optional
+        A list of keys for session tags that you want to pass to the role
+        session.
+    SourceIdentity : str, optional
+        A unique identifier that is passed in the AssumeRole call.
+    ProvidedContexts : list of ProvidedContext, optional
+        A list of context keys and values for the session.
+
+    Notes
+    -----
+    Values can be accessed via dot-notation (e.g., ``config.RoleArn``)
+    or dictionary-style access (e.g., ``config['RoleArn']``).
+
+    Accessing a valid but unset attribute (e.g., ``SerialNumber``) via
+    dot-notation returns ``None`` instead of raising an error. While this
+    behavior is convenient, it may surprise users accustomed to seeing
+    ``AttributeError`` exceptions in similar contexts.
+
+    For additional information on AWS specifications, refer to the
+    `API Reference for AssumeRole <https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html>`_.
+    """
+
+    def __init__(
+        self,
+        *,  # enforce keyword-only arguments
+        RoleArn: str,
+        RoleSessionName: str | None = None,
+        PolicyArns: list[PolicyDescriptorType] | None = None,
+        Policy: str | None = None,
+        DurationSeconds: int | None = None,
+        ExternalId: str | None = None,
+        SerialNumber: str | None = None,
+        TokenCode: str | None = None,
+        Tags: list[Tag] | None = None,
+        TransitiveTagKeys: list[str] | None = None,
+        SourceIdentity: str | None = None,
+        ProvidedContexts: list[ProvidedContext] | None = None,
+    ):
+        super().__init__(
+            RoleArn=RoleArn,
+            RoleSessionName=RoleSessionName,
+            PolicyArns=PolicyArns,
+            Policy=Policy,
+            DurationSeconds=DurationSeconds,
+            ExternalId=ExternalId,
+            SerialNumber=SerialNumber,
+            TokenCode=TokenCode,
+            Tags=Tags,
+            TransitiveTagKeys=TransitiveTagKeys,
+            SourceIdentity=SourceIdentity,
+            ProvidedContexts=ProvidedContexts,
+        )
+
+    def _validate(self, key: str, value: Any) -> None:
+        if not isinstance(key, str):
+            raise BRSValidationError("Attribute name must be a string.")
+
+        if key not in ASSUME_ROLE_CONFIG_PARAMETERS:
+            raise BRSValidationError(
+                f"'{key}' is not a valid attribute for AssumeRoleConfig."
+            )
+
+        if (
+            key == "TokenCode"
+            and isinstance(value, str)
+            and (len(value) != 6 or not value.isdigit())
+        ):
+            raise BRSValidationError(
+                f"'{key}' must be a 6-digit numeric string."
+            )
+
+
+class STSClientConfig(BaseConfig):
+    """Configuration for boto3 STS Client.
+
+    Attributes
+    ----------
+    service_name : str, optional
+        The name of the AWS service. Defaults to 'sts'.
+    region_name : str, optional
+        The AWS region name.
+    api_version : str, optional
+        The API version to use.
+    use_ssl : bool, optional
+        Whether to use SSL.
+    verify : bool or str, optional
+        Whether to verify SSL certificates or a path to a CA bundle.
+    endpoint_url : str, optional
+        The complete URL to use for the constructed client.
+    aws_access_key_id : str, optional
+        The AWS access key ID.
+    aws_secret_access_key : str, optional
+        The AWS secret access key.
+    aws_session_token : str, optional
+        The AWS session token.
+    config : botocore.config.Config, optional
+        Advanced client configuration options.
+    aws_account_id : str, optional
+        The AWS account ID associated with the credentials.
+
+    Notes
+    -----
+    Values can be accessed via dot-notation (e.g., ``config.RoleArn``)
+    or dictionary-style access (e.g., ``config['RoleArn']``).
+
+    Accessing a valid but unset attribute (e.g., ``SerialNumber``) via
+    dot-notation returns ``None`` instead of raising an error. While this
+    behavior is convenient, it may surprise users accustomed to seeing
+    ``AttributeError`` exceptions in similar contexts.
+
+    ``service_name`` is enforced to be 'sts'. If a different value is
+    provided, it will be overridden to 'sts' with a warning.
+    """
+
+    def __init__(
+        self,
+        *,  # enforce keyword-only arguments
+        service_name: str | None = None,
+        region_name: str | None = None,
+        api_version: str | None = None,
+        use_ssl: bool | None = None,
+        verify: bool | str | None = None,
+        endpoint_url: str | None = None,
+        aws_access_key_id: str | None = None,
+        aws_secret_access_key: str | None = None,
+        aws_session_token: str | None = None,
+        config: Config | None = None,
+        aws_account_id: str | None = None,
+    ):
+        super().__init__(
+            service_name=service_name,
+            region_name=region_name,
+            api_version=api_version,
+            use_ssl=use_ssl,
+            verify=verify,
+            endpoint_url=endpoint_url,
+            aws_access_key_id=aws_access_key_id,
+            aws_secret_access_key=aws_secret_access_key,
+            aws_session_token=aws_session_token,
+            config=config,
+            aws_account_id=aws_account_id,
+        )
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Override to enforce 'sts' as service_name."""
+
+        if key == "service_name":
+            match value:
+                case None:
+                    value = "sts"
+                case str() if value != "sts":
+                    BRSWarning.warn(
+                        "The 'service_name' for STSClientConfig should be "
+                        "'sts'. Overriding to 'sts'."
+                    )
+                    value = "sts"
+                case str():
+                    ...
+                case _:
+                    raise BRSValidationError(
+                        "'service_name' must be a string."
+                    )
+
+        super().__setitem__(key, value)
+
+    def _validate(self, key: str, value: Any) -> None:
+        if not isinstance(key, str):
+            raise BRSValidationError("Attribute name must be a string.")
+
+        if key not in STS_CLIENT_CONFIG_PARAMETERS:
+            raise BRSValidationError(
+                f"'{key}' is not a valid attribute for STSClientConfig."
+            )

boto3_refresh_session/utils/constants.py

@@ -2,15 +2,40 @@
 # 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__ = [
-    "ROLE_ARN_PATTERN",
-    "MFA_SERIAL_PATTERN",
-    "ROLE_SESSION_NAME_PATTERN",
-]
+__all__ = ["ASSUME_ROLE_CONFIG_PARAMETERS", "STS_CLIENT_CONFIG_PARAMETERS"]
 
 from re import compile
 
-# AWS ARN validation patterns
+# THESE CONSTANTS WILL BE DEPRECATED IN A FUTURE RELEASE!!
 ROLE_ARN_PATTERN = compile(r"^arn:aws[a-z-]*:iam::\d{12}:role/[\w+=,.@-]+$")
 MFA_SERIAL_PATTERN = compile(r"^arn:aws[a-z-]*:iam::\d{12}:mfa/[\w+=,.@-]+$")
 ROLE_SESSION_NAME_PATTERN = compile(r"^[a-zA-Z0-9+=,.@-]{2,64}$")
+
+# config parameter names
+ASSUME_ROLE_CONFIG_PARAMETERS = (
+    "RoleArn",
+    "RoleSessionName",
+    "PolicyArns",
+    "Policy",
+    "DurationSeconds",
+    "ExternalId",
+    "SerialNumber",
+    "TokenCode",
+    "Tags",
+    "TransitiveTagKeys",
+    "SourceIdentity",
+    "ProvidedContexts",
+)
+STS_CLIENT_CONFIG_PARAMETERS = (
+    "service_name",
+    "region_name",
+    "api_version",
+    "use_ssl",
+    "verify",
+    "endpoint_url",
+    "aws_access_key_id",
+    "aws_secret_access_key",
+    "aws_session_token",
+    "config",
+    "aws_account_id",
+)

boto3_refresh_session/utils/internal.py

@@ -36,9 +36,9 @@ common surface and registration behavior for subclasses like STS or IoT X.509.
 
 __all__ = [
     "AWSCRTResponse",
+    "BRSSession",
     "BaseIoTRefreshableSession",
     "BaseRefreshableSession",
-    "BRSSession",
     "CredentialProvider",
     "Registry",
     "refreshable_session",
@@ -276,9 +276,9 @@ class BRSSession(Session):
         Parameters
         ----------
         *args : Any
-            Positional arguments for :class:`boto3.session.Session.client`.
+            Positional arguments for :meth:`boto3.session.Session.client`.
         **kwargs : Any
-            Keyword arguments for :class:`boto3.session.Session.client`.
+            Keyword arguments for :meth:`boto3.session.Session.client`.
 
         Returns
         -------

boto3_refresh_session/utils/typing.py

@@ -117,6 +117,7 @@ class AssumeRoleParams(TypedDict):
 
 
 class STSClientParams(TypedDict):
+    service_name: NotRequired[str]
     region_name: NotRequired[str]
     api_version: NotRequired[str]
     use_ssl: NotRequired[bool]

{boto3_refresh_session-7.0.1.dist-info → boto3_refresh_session-7.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boto3-refresh-session
-Version: 7.0.1
+Version: 7.1.3
 Summary: A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.
 License: MPL-2.0
 License-File: LICENSE
@@ -109,7 +109,7 @@ Description-Content-Type: text/markdown
 
   <a href="https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/LICENSE">
     <img 
-      src="https://img.shields.io/github/license/michaelthomasletts/boto3-refresh-session?style=flat&labelColor=555&color=FF0000&label=📜%20License" 
+      src="https://img.shields.io/static/v1?label=License&message=MPL-2.0&color=FF0000&labelColor=555&logo=github&style=flat"
       alt="license"
     />
   </a>
@@ -123,7 +123,7 @@ Description-Content-Type: text/markdown
 
 </div>
 
-## 😛 Features
+## Features
 
 - Drop-in replacement for `boto3.session.Session`
 - MFA support included for STS
@@ -136,7 +136,7 @@ Description-Content-Type: text/markdown
     - MQTT actions are available!
 - [Tested](https://github.com/michaelthomasletts/boto3-refresh-session/tree/main/tests), [documented](https://michaelthomasletts.github.io/boto3-refresh-session/index.html), and [published to PyPI](https://pypi.org/project/boto3-refresh-session/)
 
-## 😌 Recognition and Testimonials
+## Recognition and Testimonials
 
 [Featured in TL;DR Sec.](https://tldrsec.com/p/tldr-sec-282)
 
@@ -148,19 +148,85 @@ A testimonial 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
+## Installation
+
+boto3-refresh-session is available on PyPI:
 
 ```bash
 pip install boto3-refresh-session
 ```
 
-## 📝 Usage
+## Quick Start Guide
+
+Basic, bare-bones initialization:
+
+```python
+from boto3_refresh_session import AssumeRoleConfig, RefreshableSession
+
+session = RefreshableSession(
+  AssumeRoleConfig(
+    RoleArn="<your role arn>"
+  )
+)
+```
+
+Basic initilization including some additional session parameters:
+
+```python
+from boto3_refresh_session import AssumeRoleConfig, RefreshableSession
+
+session = RefreshableSession(
+  AssumeRoleConfig(
+    RoleArn="<your role arn>"
+  ),
+  region_name="<your region name>",
+  profile_name="<your aws profile name>",
+)
+```
+
+Slightly advanced initialization using an MFA token provider (Yubikey):
+
+```python
+from boto3_refresh_session import AssumeRoleConfig, RefreshableSession
+import subprocess
+from typing import Sequence
+
+
+def mfa_token_provider(cmd: Sequence[str], timeout: float):
+  p = subprocess.run(
+    list(cmd),
+    check=False,
+    capture_output=True,
+    text=True,
+    timeout=timeout,
+  )
+  return (p.stdout or "").strip()
+
+
+mfa_token_provider_kwargs = {
+  "cmd": ["ykman", "oath", "code", "--single", "AWS-prod"],  # example token source
+  "timeout": 3.0,
+}
+
+session = RefreshableSession(
+  AssumeRoleConfig(
+    RoleArn="<your role arn>",
+    SerialNumber="<your MFA device arn>",
+  ),
+  mfa_token_provider=mfa_token_provider,
+  mfa_token_provider_kwargs=mfa_token_provider_kwargs,
+)
+```
+
+## Usage
+
+Refer to the [official usage documentation](https://michaelthomasletts.com/boto3-refresh-session/usage.html) for guidance on general usage.
 
-Refer to the [official documentation](https://michaelthomasletts.com/boto3-refresh-session/usage.html) for guidance.
+Refer to the [official API documentation](https://michaelthomasletts.com/boto3-refresh-session/modules/index.html) for technical information.
 
-## ⚠️ Changes
+## Versions
 
-Refer to the [changelog](https://michaelthomasletts.com/boto3-refresh-session/changelog.html).
+Refer to the [changelog](https://michaelthomasletts.com/boto3-refresh-session/changelog.html) for additional information on specific versions and releases.
 
 ## License
 

boto3_refresh_session-7.1.3.dist-info/RECORD

@@ -0,0 +1,21 @@
+boto3_refresh_session/__init__.py,sha256=IdfzDufhNbMK1jCkUvwCIsgYB7-OTkNZeEcWPv8FMUk,620
+boto3_refresh_session/exceptions.py,sha256=ypSr7p5Tf0k_E7cf5r-bl336vofNHGRGXsGdkQTyX58,4412
+boto3_refresh_session/methods/__init__.py,sha256=18a2jb5VvY2FdUhHJ4T1lkfotHpbAb8zdMjqxZ3e6tc,394
+boto3_refresh_session/methods/custom.py,sha256=jHRkleg9wvfJ9P0zsWezAr5-93CbXmVaWd5xYjiynBQ,5346
+boto3_refresh_session/methods/iot/__init__.py,sha256=RI9zui9I1hEwkE5N8sAs94IGLCkHF3DxRnKg6MvPESE,348
+boto3_refresh_session/methods/iot/core.py,sha256=6TInwBrNyLwQrcfLC76LRgCB75HFtF_spZ_2pCJKk0g,1532
+boto3_refresh_session/methods/iot/x509.py,sha256=01iN_eSFV2xGPWHl_VgCpf6ojRnikFDC4vNb5v1tApo,22954
+boto3_refresh_session/methods/sts.py,sha256=Z8oix37oK0ClHB_YVcsy5H2UCSJObbDbjNW3NTyNm98,9134
+boto3_refresh_session/session.py,sha256=dqcKcC3mknrolpaBv-en67__Xsn0ocJtMF_PCJaim6E,3997
+boto3_refresh_session/utils/__init__.py,sha256=B-bq0LB9XTlP6VjoGLdsIecWxzauULTRQRyEN1YYLfQ,546
+boto3_refresh_session/utils/cache.py,sha256=3zgms7KZSwPMvTnc39ndPqByB7KqpMeZwuV_bv7S6y8,3126
+boto3_refresh_session/utils/config/__init__.py,sha256=AD-dIem6xwiISXEs-xQA8NOhMKibMkBSt00kLpz8JJg,290
+boto3_refresh_session/utils/config/config.py,sha256=gfVHla7dDgrBAt9Prr_UU6WQmA6Y3lWNk6Mg5PL-tKo,9864
+boto3_refresh_session/utils/constants.py,sha256=iQ6XnSe8p9DH95Ylnhpp6-Pi6amgnBWJSBloHWBK_VA,1132
+boto3_refresh_session/utils/internal.py,sha256=Xvo3D5_MFoldmqNISOmfQf7qydIbQOCVE-0EQY_8pjg,14755
+boto3_refresh_session/utils/typing.py,sha256=pfUP9bGHoh5JlfMBJL-yDBLYykE2gu2A55uLsOS1tVs,3407
+boto3_refresh_session-7.1.3.dist-info/METADATA,sha256=ZJvtmiLo52bygfZHP6HnHVa86ckySU6EbgJcXSmFdCw,8457
+boto3_refresh_session-7.1.3.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+boto3_refresh_session-7.1.3.dist-info/licenses/LICENSE,sha256=hs-WVkefHtuCJFuYX0oswNUDuUV2br7aQmnGCzB2ma4,16725
+boto3_refresh_session-7.1.3.dist-info/licenses/NOTICE,sha256=4nNFSLvbelWrxMEBMrkcmgi93AaF0NckUgNIf9i6Kbs,863
+boto3_refresh_session-7.1.3.dist-info/RECORD,,

boto3_refresh_session-7.0.1.dist-info/RECORD

@@ -1,19 +0,0 @@
-boto3_refresh_session/__init__.py,sha256=tUnT4evpnXX_TNcqBXOmtziC02jrsCQ6ryCj33vEOwQ,620
-boto3_refresh_session/exceptions.py,sha256=y4jQ-kjbyprJxSD7HnqzoCZqMnmNqj6TgmTuua7ba2k,4412
-boto3_refresh_session/methods/__init__.py,sha256=18a2jb5VvY2FdUhHJ4T1lkfotHpbAb8zdMjqxZ3e6tc,394
-boto3_refresh_session/methods/custom.py,sha256=jHRkleg9wvfJ9P0zsWezAr5-93CbXmVaWd5xYjiynBQ,5346
-boto3_refresh_session/methods/iot/__init__.py,sha256=RI9zui9I1hEwkE5N8sAs94IGLCkHF3DxRnKg6MvPESE,348
-boto3_refresh_session/methods/iot/core.py,sha256=6TInwBrNyLwQrcfLC76LRgCB75HFtF_spZ_2pCJKk0g,1532
-boto3_refresh_session/methods/iot/x509.py,sha256=01iN_eSFV2xGPWHl_VgCpf6ojRnikFDC4vNb5v1tApo,22954
-boto3_refresh_session/methods/sts.py,sha256=ll6zjAuelUu-rNVKDn4PdUKu4YESafVFVJgWV--GnHw,11114
-boto3_refresh_session/session.py,sha256=5xg6SprpdPvGgAC1cPRZy983EnVh3z9xJ0PBRO5L7VI,3643
-boto3_refresh_session/utils/__init__.py,sha256=WWHRpVzj0HMqWCLhm4vr2aV678gqA5q-FN2-7OZJe-Q,485
-boto3_refresh_session/utils/cache.py,sha256=3zgms7KZSwPMvTnc39ndPqByB7KqpMeZwuV_bv7S6y8,3126
-boto3_refresh_session/utils/constants.py,sha256=3Kp4JVrDdeFCknb87wK0GjGzX8xMkkILxAYArIsP5mo,574
-boto3_refresh_session/utils/internal.py,sha256=HS1drA0F1kzsAG_i_MXN6n1LBmTEU5DLrv3SsSGvZK4,14757
-boto3_refresh_session/utils/typing.py,sha256=GPUADnET8WqNLt6k8sXNimRsCY9dZmxv-fV3g2dYBfY,3372
-boto3_refresh_session-7.0.1.dist-info/METADATA,sha256=nkutVfNQ9MeoyOkXIZ4IsrdNhYea47wu0EgSLagLAyk,6905
-boto3_refresh_session-7.0.1.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
-boto3_refresh_session-7.0.1.dist-info/licenses/LICENSE,sha256=hs-WVkefHtuCJFuYX0oswNUDuUV2br7aQmnGCzB2ma4,16725
-boto3_refresh_session-7.0.1.dist-info/licenses/NOTICE,sha256=4nNFSLvbelWrxMEBMrkcmgi93AaF0NckUgNIf9i6Kbs,863
-boto3_refresh_session-7.0.1.dist-info/RECORD,,