boto3-refresh-session 0.1.23__tar.gz → 1.0.0__tar.gz

{boto3_refresh_session-0.1.23 → boto3_refresh_session-1.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: boto3-refresh-session
-Version: 0.1.23
-Summary: A simple Python package for refreshing AWS temporary credentials in boto3 automatically.
+Version: 1.0.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
 Author: Mike Letts
@@ -15,7 +15,6 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: attrs (>=24.3.0,<25.0.0)
 Requires-Dist: boto3
 Requires-Dist: botocore
 Project-URL: Documentation, https://michaelthomasletts.github.io/boto3-refresh-session/index.html
@@ -27,17 +26,16 @@ Description-Content-Type: text/markdown
 [![Workflow](https://img.shields.io/github/actions/workflow/status/michaelthomasletts/boto3-refresh-session/push.yml?logo=github)](https://github.com/michaelthomasletts/boto3-refresh-session/actions/workflows/push_pullrequest.yml)
 ![Python Version](https://img.shields.io/pypi/pyversions/boto3-refresh-session?style=pypi)
 ![GitHub last commit](https://img.shields.io/github/last-commit/michaelthomasletts/boto3-refresh-session?logo=github)
-![GitHub Repo stars](https://img.shields.io/github/stars/michaelthomasletts/boto3-refresh-session?logo=github)
-![GitHub forks](https://img.shields.io/github/forks/michaelthomasletts/boto3-refresh-session?logo=github)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/boto3-refresh-session?logo=pypi)
 
 ![BRS Image](https://raw.githubusercontent.com/michaelthomasletts/boto3-refresh-session/refs/heads/main/doc/brs.png)
 
-A simple Python package for refreshing AWS temporary credentials in ``boto3`` automatically.
+A simple Python package for refreshing the temporary security credentials in a `boto3.session.Session` object automatically.
 
 - [Documentation](https://michaelthomasletts.github.io/boto3-refresh-session/index.html)
 - [Source Code](https://github.com/michaelthomasletts/boto3-refresh-session)
 - [PyPI](https://pypi.org/project/boto3-refresh-session/)
+- [Contributing](https://michaelthomasletts.github.io/boto3-refresh-session/contributing.html)
 
 ### Why should I use this?
 
@@ -45,9 +43,9 @@ It is common for data pipelines and workflows that interact with the AWS API via
 `boto3` to run for a long time and, accordingly, for temporary credentials to 
 expire. 
 
-Usually, engineers deal with that problem one of two ways: 
+Usually, engineers deal with that problem one of two different ways: 
 
-- `try except` blocks that catch `ClientError` exceptions
+- A `try except` block that catches `botocore.exceptions.ClientError` exceptions
 - A similar approach as that used in this project -- that is, using methods available 
   within `botocore` for refreshing temporary credentials automatically. 
   
@@ -64,10 +62,10 @@ If any of that sounds relatable, then `boto3-refresh-session` should help you!
 
 ### Usage
 
-Simply pass the basic parameters and initialize the `AutoRefreshableSession` object; 
+Simply pass the basic parameters and initialize the `RefreshableSession` object; 
 that's it! You're good to go!
 
-`AutoRefreshableSession` will refresh
+`RefreshableSession` will refresh
 temporary credentials for you in the background. In the following example,
 continue using the `s3_client` object without worry of using `try` and 
 `except` blocks!
@@ -79,13 +77,22 @@ machine, check [this documentation](https://boto3.amazonaws.com/v1/documentation
 ```python
 import boto3_refresh_session as brs
 
-
-sess = brs.AutoRefreshableSession(
-    region="<your-region>",
-    role_arn="<your-role-arn>",
-    session_name="<your-session-name>",
+assume_role_kwargs = {
+  'RoleArn': '<your-role-arn>',
+  'RoleSessionName': '<your-role-session-name>',
+  'DurationSeconds': '<your-selection>',
+  ...
+}
+sts_client_kwargs = {
+  ...
+}
+session = brs.RefreshableSession(
+  assume_role_kwargs=assume_role_kwargs,
+  sts_client_kwargs=sts_client_kwargs,
+  region_name='us-east-1',
 )
-s3_client = sess.session.client(service_name="s3")
+s3 = session.client(service_name='s3')
+buckets = s3.list_buckets()
 ```
 
 ### Installation

{boto3_refresh_session-0.1.23 → boto3_refresh_session-1.0.0}/README.md

@@ -3,17 +3,16 @@
 [![Workflow](https://img.shields.io/github/actions/workflow/status/michaelthomasletts/boto3-refresh-session/push.yml?logo=github)](https://github.com/michaelthomasletts/boto3-refresh-session/actions/workflows/push_pullrequest.yml)
 ![Python Version](https://img.shields.io/pypi/pyversions/boto3-refresh-session?style=pypi)
 ![GitHub last commit](https://img.shields.io/github/last-commit/michaelthomasletts/boto3-refresh-session?logo=github)
-![GitHub Repo stars](https://img.shields.io/github/stars/michaelthomasletts/boto3-refresh-session?logo=github)
-![GitHub forks](https://img.shields.io/github/forks/michaelthomasletts/boto3-refresh-session?logo=github)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/boto3-refresh-session?logo=pypi)
 
 ![BRS Image](https://raw.githubusercontent.com/michaelthomasletts/boto3-refresh-session/refs/heads/main/doc/brs.png)
 
-A simple Python package for refreshing AWS temporary credentials in ``boto3`` automatically.
+A simple Python package for refreshing the temporary security credentials in a `boto3.session.Session` object automatically.
 
 - [Documentation](https://michaelthomasletts.github.io/boto3-refresh-session/index.html)
 - [Source Code](https://github.com/michaelthomasletts/boto3-refresh-session)
 - [PyPI](https://pypi.org/project/boto3-refresh-session/)
+- [Contributing](https://michaelthomasletts.github.io/boto3-refresh-session/contributing.html)
 
 ### Why should I use this?
 
@@ -21,9 +20,9 @@ It is common for data pipelines and workflows that interact with the AWS API via
 `boto3` to run for a long time and, accordingly, for temporary credentials to 
 expire. 
 
-Usually, engineers deal with that problem one of two ways: 
+Usually, engineers deal with that problem one of two different ways: 
 
-- `try except` blocks that catch `ClientError` exceptions
+- A `try except` block that catches `botocore.exceptions.ClientError` exceptions
 - A similar approach as that used in this project -- that is, using methods available 
   within `botocore` for refreshing temporary credentials automatically. 
   
@@ -40,10 +39,10 @@ If any of that sounds relatable, then `boto3-refresh-session` should help you!
 
 ### Usage
 
-Simply pass the basic parameters and initialize the `AutoRefreshableSession` object; 
+Simply pass the basic parameters and initialize the `RefreshableSession` object; 
 that's it! You're good to go!
 
-`AutoRefreshableSession` will refresh
+`RefreshableSession` will refresh
 temporary credentials for you in the background. In the following example,
 continue using the `s3_client` object without worry of using `try` and 
 `except` blocks!
@@ -55,13 +54,22 @@ machine, check [this documentation](https://boto3.amazonaws.com/v1/documentation
 ```python
 import boto3_refresh_session as brs
 
-
-sess = brs.AutoRefreshableSession(
-    region="<your-region>",
-    role_arn="<your-role-arn>",
-    session_name="<your-session-name>",
+assume_role_kwargs = {
+  'RoleArn': '<your-role-arn>',
+  'RoleSessionName': '<your-role-session-name>',
+  'DurationSeconds': '<your-selection>',
+  ...
+}
+sts_client_kwargs = {
+  ...
+}
+session = brs.RefreshableSession(
+  assume_role_kwargs=assume_role_kwargs,
+  sts_client_kwargs=sts_client_kwargs,
+  region_name='us-east-1',
 )
-s3_client = sess.session.client(service_name="s3")
+s3 = session.client(service_name='s3')
+buckets = s3.list_buckets()
 ```
 
 ### Installation

boto3_refresh_session-1.0.0/boto3_refresh_session/__init__.py

@@ -0,0 +1,6 @@
+__all__ = []
+
+from . import session
+from .session import RefreshableSession
+
+__all__.extend(["session", "RefreshableSession"])

boto3_refresh_session-1.0.0/boto3_refresh_session/session.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+__doc__ = """
+A :class:`boto3.session.Session` object that automatically refreshes temporary
+credentials.
+"""
+__all__ = ["RefreshableSession"]
+
+from boto3 import client
+from boto3.session import Session
+from botocore.credentials import (
+    DeferredRefreshableCredentials,
+    RefreshableCredentials,
+)
+
+
+class RefreshableSession(Session):
+    """Returns a :class:`boto3.session.Session` object with temporary credentials
+    that refresh automatically.
+
+    Parameters
+    ----------
+    assume_role_kwargs : dict
+        Required keyword arguments for the :meth:`STS.Client.assume_role` method.
+    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``.
+    sts_client_kwargs : dict, optional
+        Optional keyword arguments for the :class:`STS.Client` object. Default is
+        an empty dictionary.
+
+    Other Parameters
+    ----------------
+    kwargs : dict
+        Optional keyword arguments for the :class:`boto3.session.Session` object.
+
+    Notes
+    -----
+    Check the :ref:`authorization documentation <authorization>` for additional
+    information concerning how to authorize access to AWS.
+
+    Check the `AWS documentation <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html>`_
+    for additional information concerning temporary security credentials in IAM.
+
+    Examples
+    --------
+    In order to use this object, you are required to configure parameters for the
+    :meth:`STS.Client.assume_role` method.
+
+    >>> assume_role_kwargs = {
+    >>>     'RoleArn': '<your-role-arn>',
+    >>>     'RoleSessionName': '<your-role-session-name>',
+    >>>     'DurationSeconds': '<your-selection>',
+    >>>     ...
+    >>> }
+
+    You may also want to provide optional parameters for the :class:`STS.Client` object.
+
+    >>> sts_client_kwargs = {
+    >>>     ...
+    >>> }
+
+    You may also provide optional parameters for the :class:`boto3.session.Session` object
+    when initializing the ``RefreshableSession`` object. Below, we use the ``region_name``
+    parameter for illustrative purposes.
+
+    >>> session = boto3_refresh_session.RefreshableSession(
+    >>>     assume_role_kwargs=assume_role_kwargs,
+    >>>     sts_client_kwargs=sts_client_kwargs,
+    >>>     region_name='us-east-1',
+    >>> )
+
+    Using the ``session`` variable that you just created, you can now use all of the methods
+    available from the :class:`boto3.session.Session` object. In the below example, we
+    initialize an S3 client and list all available buckets.
+
+    >>> s3 = session.client(service_name='s3')
+    >>> buckets = s3.list_buckets()
+
+    There are two ways of refreshing temporary credentials automatically with the
+    ``RefreshableSession`` object: refresh credentials the moment they expire, or wait until
+    temporary credentials are explicitly needed. The latter is the default. The former must
+    be configured using the ``defer_refresh`` parameter, as shown below.
+
+    >>> session = boto3_refresh_session.RefreshableSession(
+    >>>     defer_refresh=False,
+    >>>     assume_role_kwargs=assume_role_kwargs,
+    >>>     sts_client_kwargs=sts_client_kwargs,
+    >>>     region_name='us-east-1',
+    >>> )
+    """
+
+    def __init__(
+        self,
+        assume_role_kwargs: dict,
+        defer_refresh: bool = True,
+        sts_client_kwargs: dict = {},
+        **kwargs,
+    ):
+        # inheriting from boto3.session.Session
+        super().__init__(**kwargs)
+
+        # initializing custom parameters that are necessary outside of __init__
+        self.assume_role_kwargs = assume_role_kwargs
+
+        # initializing the STS client
+        self._sts_client = client(service_name="sts", **sts_client_kwargs)
+
+        # determining how exactly to refresh expired temporary credentials
+        if not defer_refresh:
+            self._session._credentials = (
+                RefreshableCredentials.create_from_metadata(
+                    metadata=self._get_credentials(),
+                    refresh_using=self._get_credentials,
+                    method="sts-assume-role",
+                )
+            )
+        else:
+            self._session._credentials = DeferredRefreshableCredentials(
+                refresh_using=self._get_credentials, method="sts-assume-role"
+            )
+
+    def _get_credentials(self) -> dict:
+        """Returns temporary credentials via AWS STS.
+
+        Returns
+        -------
+        dict
+            AWS temporary credentials.
+        """
+
+        # fetching temporary credentials
+        _temporary_credentials = self._sts_client.assume_role(
+            **self.assume_role_kwargs
+        )["Credentials"]
+        return {
+            "access_key": _temporary_credentials.get("AccessKeyId"),
+            "secret_key": _temporary_credentials.get("SecretAccessKey"),
+            "token": _temporary_credentials.get("SessionToken"),
+            "expiry_time": _temporary_credentials.get(
+                "Expiration"
+            ).isoformat(),
+        }

{boto3_refresh_session-0.1.23 → boto3_refresh_session-1.0.0}/pyproject.toml

@@ -1,14 +1,14 @@
 [project]
 name = "boto3-refresh-session"
-version = "0.1.23"
-description = "A simple Python package for refreshing AWS temporary credentials in boto3 automatically."
+version = "1.0.0"
+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"}
 ]
 license = {text = "MIT"}
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = ["boto3", "botocore", "attrs (>=24.3.0,<25.0.0)"]
+dependencies = ["boto3", "botocore"]
 keywords = ["boto3", "botocore", "aws"]
 maintainers = [
   {name="Michael Letts", email="lettsmt@gmail.com"},

boto3_refresh_session-0.1.23/boto3_refresh_session/__init__.py

@@ -1,6 +0,0 @@
-__all__ = []
-
-from . import session
-from .session import AutoRefreshableSession
-
-__all__.extend(["session", "AutoRefreshableSession"])

boto3_refresh_session-0.1.23/boto3_refresh_session/session.py

@@ -1,171 +0,0 @@
-from __future__ import annotations
-
-__doc__ = """
-Helper method for generating an automatically refreshing :class:`boto3.session.Session`
-object.
-
-.. warning::
-    ``AutoRefreshableSession`` was not tested for manually passing hard-coded
-    account credentials to the ``boto3.client`` object! There is an optional 
-    ``client_kwargs`` parameter available for doing so, which *should* work; 
-    however, that cannot be guaranteed as that functionality was not tested.
-    Pass hard-coded credentials with the ``client_kwargs`` parameter at your
-    own discretion.
-"""
-__all__ = ["AutoRefreshableSession"]
-
-from logging import INFO, basicConfig, getLogger
-from typing import Type
-
-from attrs import define, field
-from attrs.validators import ge, instance_of, optional
-from boto3 import Session, client
-from botocore.credentials import (
-    DeferredRefreshableCredentials,
-    RefreshableCredentials,
-)
-from botocore.session import get_session
-
-# configuring logging
-basicConfig(
-    level=INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-)
-
-# creating logger
-logger = getLogger(__name__)
-
-
-@define
-class AutoRefreshableSession:
-    """Returns a :class:`boto3.session.Session` object which refreshes automatically, no extra
-    steps required.
-
-    This object is useful for long-running processes where temporary credentials
-    may expire.
-
-    Parameters
-    ----------
-    region : str
-        AWS region name.
-    role_arn : str
-        AWS role ARN.
-    session_name : str
-        Name for session.
-    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. Default is ``True``.
-    ttl : int, optional
-        Number of seconds until temporary credentials expire. Must be greater than or
-        equal to 900 seconds. Default is 900.
-    session_kwargs : dict, optional
-        Optional keyword arguments for :class:`boto3.session.Session`.
-    client_kwargs : dict, optional
-        Optional keyword arguments for ``boto3.client``.
-
-    Attributes
-    ----------
-    session
-        Returns a :class:`boto3.session.Session` object with credentials which refresh
-        automatically.
-
-    Notes
-    -----
-    Check the :ref:`authorization documentation <authorization>` for additional
-    information concerning how to authorize access to AWS.
-
-    The default ``defer_refresh`` parameter value results in temporary credentials not
-    being refreshed until they are explicitly requested; that is more efficient than
-    refreshing expired temporary credentials automatically after they expire.
-
-    Examples
-    --------
-    Here's how to initialize this object:
-
-    >>> sess = brs.AutoRefreshableSession(
-    >>>   region="us-east-1",
-    >>>   role_arn="<your-arn>",
-    >>>   session_name="test",
-    >>> )
-    >>> s3_client = sess.session.client(service_name="s3")
-    """
-
-    region: str = field(validator=instance_of(str))
-    role_arn: str = field(validator=instance_of(str))
-    session_name: str = field(validator=instance_of(str))
-    defer_refresh: bool = field(default=True, validator=instance_of(bool))
-    ttl: int = field(
-        default=900, validator=optional([instance_of(int), ge(900)])
-    )
-    session_kwargs: dict = field(
-        default={}, validator=optional(instance_of(dict))
-    )
-    client_kwargs: dict = field(
-        default={}, validator=optional(instance_of(dict))
-    )
-    session: Type[Session] = field(init=False)
-    _creds_already_fetched: int = field(init=False, default=0)
-    _sts_client: Type["botocore.client.STS"] = field(init=False)
-
-    def __attrs_post_init__(self):
-        # initializing session
-        _session = get_session()
-
-        # initializing STS client
-        self._sts_client = client(
-            service_name="sts", region_name=self.region, **self.client_kwargs
-        )
-
-        logger.info("Fetching temporary AWS credentials.")
-
-        # determining how to refresh expired temporary credentials
-        if not self.defer_refresh:
-            __credentials = RefreshableCredentials.create_from_metadata(
-                metadata=self._get_credentials(),
-                refresh_using=self._get_credentials,
-                method="sts-assume-role",
-            )
-        else:
-            __credentials = DeferredRefreshableCredentials(
-                refresh_using=self._get_credentials, method="sts-assume-role"
-            )
-
-        # mounting temporary credentials to session object
-        _session._credentials = __credentials
-
-        # initializing session using temporary credentials
-        self.session = Session(
-            botocore_session=_session, **self.session_kwargs
-        )
-
-    def _get_credentials(self) -> dict:
-        """Returns temporary credentials via AWS STS.
-
-        Returns
-        -------
-        dict
-            AWS temporary credentials.
-        """
-
-        # being careful not to duplicate logs
-        if (self.defer_refresh and self._creds_already_fetched) or (
-            not self.defer_refresh and self._creds_already_fetched > 1
-        ):
-            logger.info("Refreshing temporary AWS credentials")
-        else:
-            self._creds_already_fetched += 1
-
-        # fetching temporary credentials
-        _temporary_credentials = self._sts_client.assume_role(
-            RoleArn=self.role_arn,
-            RoleSessionName=self.session_name,
-            DurationSeconds=self.ttl,
-        )["Credentials"]
-        return {
-            "access_key": _temporary_credentials.get("AccessKeyId"),
-            "secret_key": _temporary_credentials.get("SecretAccessKey"),
-            "token": _temporary_credentials.get("SessionToken"),
-            "expiry_time": _temporary_credentials.get(
-                "Expiration"
-            ).isoformat(),
-        }