boto3-refresh-session 1.1.2__py3-none-any.whl → 1.2.0__py3-none-any.whl

boto3_refresh_session/__init__.py

@@ -1,6 +1,7 @@
+from .ecs import ECSRefreshableSession
 from .session import RefreshableSession
 from .sts import STSRefreshableSession
 
 __all__ = ["RefreshableSession"]
-__version__ = "1.1.2"
+__version__ = "1.2.0"
 __author__ = "Mike Letts"

boto3_refresh_session/ecs.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+__all__ = ["ECSRefreshableSession"]
+
+import os
+
+import requests
+
+from .exceptions import BRSError
+from .session import BaseRefreshableSession
+
+_ECS_CREDENTIALS_RELATIVE_URI = "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI"
+_ECS_CREDENTIALS_FULL_URI = "AWS_CONTAINER_CREDENTIALS_FULL_URI"
+_ECS_AUTHORIZATION_TOKEN = "AWS_CONTAINER_AUTHORIZATION_TOKEN"
+_DEFAULT_ENDPOINT_BASE = "http://169.254.170.2"
+
+
+class ECSRefreshableSession(BaseRefreshableSession, method="ecs"):
+    """A boto3 session that automatically refreshes temporary AWS credentials
+    from the ECS container credentials metadata endpoint.
+
+    Parameters
+    ----------
+    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``.
+
+    Other Parameters
+    ----------------
+    kwargs : dict
+        Optional keyword arguments passed to :class:`boto3.session.Session`.
+    """
+
+    def __init__(self, defer_refresh: bool | None = None, **kwargs):
+        super().__init__(**kwargs)
+
+        self._endpoint = self._resolve_endpoint()
+        self._headers = self._build_headers()
+        self._http = self._init_http_session()
+
+        self._refresh_using(
+            credentials_method=self._get_credentials,
+            defer_refresh=defer_refresh is not False,
+            refresh_method="ecs-container-metadata",
+        )
+
+    def _resolve_endpoint(self) -> str:
+        uri = os.environ.get(_ECS_CREDENTIALS_FULL_URI) or os.environ.get(
+            _ECS_CREDENTIALS_RELATIVE_URI
+        )
+        if not uri:
+            raise BRSError(
+                "Neither AWS_CONTAINER_CREDENTIALS_FULL_URI nor "
+                "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is set. "
+                "Are you running inside an ECS container?"
+            )
+        if uri.startswith("http://") or uri.startswith("https://"):
+            return uri
+        return f"{_DEFAULT_ENDPOINT_BASE}{uri}"
+
+    def _build_headers(self) -> dict[str, str]:
+        token = os.environ.get(_ECS_AUTHORIZATION_TOKEN)
+        if token:
+            return {"Authorization": f"Bearer {token}"}
+        return {}
+
+    def _init_http_session(self) -> requests.Session:
+        session = requests.Session()
+        session.headers.update(self._headers)
+        return session
+
+    def _get_credentials(self) -> dict[str, str]:
+        try:
+            response = self._http.get(self._endpoint, timeout=3)
+            response.raise_for_status()
+        except requests.RequestException as exc:
+            raise BRSError(
+                f"Failed to retrieve ECS credentials from {self._endpoint}"
+            ) from exc
+
+        credentials = response.json()
+        required = {
+            "AccessKeyId",
+            "SecretAccessKey",
+            "SessionToken",
+            "Expiration",
+        }
+        if not required.issubset(credentials):
+            raise BRSError(f"Incomplete credentials received: {credentials}")
+        return {
+            "access_key": credentials.get("AccessKeyId"),
+            "secret_key": credentials.get("SecretAccessKey"),
+            "token": credentials.get("SessionToken"),
+            "expiry_time": credentials.get("Expiration"),  # already ISO8601
+        }
+
+    @staticmethod
+    def get_identity() -> dict[str, str]:
+        """Returns metadata about ECS.
+
+        Returns
+        -------
+        dict[str, str]
+            Dict containing metadata about ECS.
+        """
+
+        return {"method": "ecs", "source": "ecs-container-metadata"}

boto3_refresh_session/exceptions.py

@@ -0,0 +1,38 @@
+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__}({repr(self.message)})"
+
+
+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__}({repr(self.message)})"

boto3_refresh_session/session.py

@@ -1,44 +1,9 @@
 from __future__ import annotations
 
-__doc__ = """
-boto3_refresh_session.session
-=============================
-
-This module provides the main interface for constructing refreshable boto3 sessions.
-
-The ``RefreshableSession`` class serves as a factory that dynamically selects the appropriate 
-credential refresh strategy based on the ``method`` parameter, e.g., ``sts``.
-
-Users can interact with AWS services just like they would with a normal :class:`boto3.session.Session`, 
-with the added benefit of automatic credential refreshing.
-
-Examples
---------
->>> from boto3_refresh_session import RefreshableSession
->>> session = RefreshableSession(
-...     assume_role_kwargs={"RoleArn": "...", "RoleSessionName": "..."},
-...     region_name="us-east-1"
-... )
->>> s3 = session.client("s3")
->>> s3.list_buckets()
-
-.. seealso::
-    :class:`boto3_refresh_session.sts.STSRefreshableSession`
-
-Factory interface
------------------
-.. autosummary::
-   :toctree: generated/
-   :nosignatures:
-
-   RefreshableSession
-"""
-
 __all__ = ["RefreshableSession"]
 
 from abc import ABC, abstractmethod
 from typing import Any, Callable, ClassVar, Literal, get_args
-from warnings import warn
 
 from boto3.session import Session
 from botocore.credentials import (
@@ -46,9 +11,11 @@ from botocore.credentials import (
     RefreshableCredentials,
 )
 
+from .exceptions import BRSError, BRSWarning
+
 #: Type alias for all currently available credential refresh methods.
-Method = Literal["sts"]
-RefreshMethod = Literal["sts-assume-role"]
+Method = Literal["sts", "ecs"]
+RefreshMethod = Literal["sts-assume-role", "ecs-container-metadata"]
 
 
 class BaseRefreshableSession(ABC, Session):
@@ -77,7 +44,9 @@ class BaseRefreshableSession(ABC, Session):
 
         # guarantees that methods are unique
         if method in BaseRefreshableSession.registry:
-            warn(f"Method '{method}' is already registered. Overwriting.")
+            BRSWarning(
+                f"Method {repr(method)} is already registered. Overwriting."
+            )
 
         BaseRefreshableSession.registry[method] = cls
 
@@ -108,6 +77,34 @@ class BaseRefreshableSession(ABC, Session):
                 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
@@ -134,11 +131,18 @@ class RefreshableSession:
     See Also
     --------
     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)
 

boto3_refresh_session/sts.py

@@ -1,49 +1,10 @@
 from __future__ import annotations
 
-__doc__ = """
-boto3_refresh_session.sts
-=========================
-
-Implements the STS-based credential refresh strategy for use with 
-:class:`boto3_refresh_session.session.RefreshableSession`.
-
-This module defines the :class:`STSRefreshableSession` class, which uses 
-IAM role assumption via STS to automatically refresh temporary credentials 
-in the background.
-
-.. versionadded:: 1.1.0
-
-Examples
---------
->>> from boto3_refresh_session import RefreshableSession
->>> session = RefreshableSession(
-...     method="sts",
-...     assume_role_kwargs={
-...         "RoleArn": "arn:aws:iam::123456789012:role/MyRole",
-...         "RoleSessionName": "my-session"
-...     },
-...     region_name="us-east-1"
-... )
->>> s3 = session.client("s3")
->>> s3.list_buckets()
-
-.. seealso::
-    :class:`boto3_refresh_session.session.RefreshableSession`
-
-STS
----    
-
-.. autosummary::
-   :toctree: generated/
-   :nosignatures:
-
-   STSRefreshableSession
-"""
 __all__ = ["STSRefreshableSession"]
 
 from typing import Any
-from warnings import warn
 
+from .exceptions import BRSWarning
 from .session import BaseRefreshableSession
 
 
@@ -73,7 +34,7 @@ class STSRefreshableSession(BaseRefreshableSession, method="sts"):
     def __init__(
         self,
         assume_role_kwargs: dict,
-        defer_refresh: bool = None,
+        defer_refresh: bool | None = None,
         sts_client_kwargs: dict | None = None,
         **kwargs,
     ):
@@ -84,8 +45,8 @@ class STSRefreshableSession(BaseRefreshableSession, method="sts"):
         if sts_client_kwargs is not None:
             # overwriting 'service_name' in case it appears in sts_client_kwargs
             if "service_name" in sts_client_kwargs:
-                warn(
-                    "The sts_client_kwargs parameter cannot contain values for service_name. Reverting to service_name = 'sts'."
+                BRSWarning(
+                    "'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(

{boto3_refresh_session-1.1.2.dist-info → boto3_refresh_session-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: boto3-refresh-session
-Version: 1.1.2
+Version: 1.2.0
 Summary: A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.
 License: MIT
 Keywords: boto3,botocore,aws
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
   </a>
 
   <a href="https://pepy.tech/project/boto3-refresh-session">
-    <img src="https://img.shields.io/badge/downloads-58.3K-red?logo=python&color=%23FF0000&label=Downloads" alt="Downloads"/>
+    <img src="https://img.shields.io/badge/downloads-59.6K-red?logo=python&color=%23FF0000&label=Downloads" alt="Downloads"/>
   </a>
 
   <a href="https://michaelthomasletts.github.io/boto3-refresh-session/index.html">
@@ -77,6 +77,7 @@ Description-Content-Type: text/markdown
 
 - Auto-refreshing credentials for long-lived `boto3` sessions
 - Drop-in replacement for `boto3.session.Session`
+- Supports automatic refresh methods for STS and ECS
 - Supports `assume_role` configuration, custom STS clients, and profile / region configuration, as well as all other parameters supported by `boto3.session.Session`
 - Tested, documented, and published to PyPI
 

boto3_refresh_session-1.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+boto3_refresh_session/__init__.py,sha256=hJpUIAjfhv-ByWbDCqJfw0sEESVxVnxvZ-aOnVNXu90,200
+boto3_refresh_session/ecs.py,sha256=WIC5mlbcEnM1oo-QXmmtiw2mjFDn01hBfcFh67ku42A,3713
+boto3_refresh_session/exceptions.py,sha256=qcFzdIuK5PZirs77H_Kb64S9QFb6cn2OJtirjvaRLiY,972
+boto3_refresh_session/session.py,sha256=MtaTVdAy-Yx7x_x9SUJ0FlQs0w_8D3kHjvOS8C3bK2E,5226
+boto3_refresh_session/sts.py,sha256=paIgbmn9a3cATNX-6AEGxnSGNZnX1pj4rRQmh8gQSKs,3132
+boto3_refresh_session-1.2.0.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
+boto3_refresh_session-1.2.0.dist-info/METADATA,sha256=PafbLjHvZ4mZKyVduLho8Szruoq0P4lB_2Nv0aMFTyE,7586
+boto3_refresh_session-1.2.0.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
+boto3_refresh_session-1.2.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+boto3_refresh_session-1.2.0.dist-info/RECORD,,

boto3_refresh_session/how.py

@@ -1,44 +0,0 @@
-s = """
-lbh orybat gb zr,
-naq v, lbh.
-
-jr ner abg jub jr fnl jr ner.
-abg jub jr guvax jr ner.
-jr ner jub bguref guvax jr ner --
-jung bhe npgvbaf fnl jr ner.
-
-fb znxr jung lbh ohvyq frysyrff.
-ornhgvshy. ebohfg. cresrpg.
-
-zrqvbpevgl yherf hf sebz qvivavgl.
-gur pybfre gb cresrpgvba jr nfpraq,
-gur zber fgevqrag rivy tebjf --
-orpnhfr rivy pnaabg rkvfg 
-vs nyy vf cresrpg.
-
-n guvat vf jung vg vf abg.
-n guvat jvgu ab bgure vf abguvat.
-naq abguvat
-vf gur zbfg cresrpg guvat bs nyy.
-
-ubjrire lbh hfr guvf fbsgjner,
-jungrire lbh ohvyq --
-znxr vg cresrpg.
-qb fb sbe rirelbar ohg lbhefrys.
-
-znl jr or sbetbggra
-naq bhe npgvbaf svanyyl fvyrag.
-"""
-
-
-def how(text: str, shift: int = 13) -> str:
-    def rotate(c: str) -> str:
-        if 'a' <= c <= 'z':
-            return chr((ord(c) - ord('a') + shift) % 26 + ord('a'))
-        elif 'A' <= c <= 'Z':
-            return chr((ord(c) - ord('A') + shift) % 26 + ord('A'))
-        return c
-    return ''.join(rotate(c) for c in text)
-
-
-print(how(s.strip()))

boto3_refresh_session-1.1.2.dist-info/RECORD

@@ -1,9 +0,0 @@
-boto3_refresh_session/__init__.py,sha256=WPNU8U79usNSOl7FKoeBQrUhdaX4Yvtpwl8eJbQcTXI,161
-boto3_refresh_session/how.py,sha256=zBfxfvQCzqJT8VJ8VTmUUzQUupRkSYXP8yOzvIXruUU,994
-boto3_refresh_session/session.py,sha256=J3FW6nkc_s9C0gj1Xs1wKaCWQMzR6S4ncDKDqu1DYxk,4879
-boto3_refresh_session/sts.py,sha256=P8lWxQLslXDeYSuvHuy0Le6CC5SIXxQ9D5DZFmwwE1Q,4057
-boto3_refresh_session-1.1.2.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
-boto3_refresh_session-1.1.2.dist-info/METADATA,sha256=25RIB9z4wwR1D3Gts08W6tNDkxH-5hW0Hz8hBX9KOYk,7533
-boto3_refresh_session-1.1.2.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
-boto3_refresh_session-1.1.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-boto3_refresh_session-1.1.2.dist-info/RECORD,,