boto3-assist 0.14.0__tar.gz → 0.16.0__tar.gz

{boto3_assist-0.14.0 → boto3_assist-0.16.0}/.gitignore

@@ -164,4 +164,5 @@ cython_debug/
 .imports
 .env.development
 .unittest
-.unittests
+.unittests
+.outputs

{boto3_assist-0.14.0 → boto3_assist-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boto3_assist
-Version: 0.14.0
+Version: 0.16.0
 Summary: Additional boto3 wrappers to make your life a little easier
 Author-email: Eric Wilson <boto3-assist@geekcafe.com>
 License-File: LICENSE-EXPLAINED.txt

{boto3_assist-0.14.0 → boto3_assist-0.16.0}/pyproject.toml

@@ -15,7 +15,7 @@ addopts = "-m 'not integration'"
 
 [project]
 name = "boto3_assist"
-version = "0.14.0"
+version = "0.16.0"
 
 authors = [
   { name="Eric Wilson", email="boto3-assist@geekcafe.com" }

boto3_assist-0.16.0/src/boto3_assist/aws_config.py

@@ -0,0 +1,199 @@
+import os
+from pathlib import Path
+import configparser
+from typing import Literal, Optional
+from boto3_assist.utilities.serialization_utility import SerializableModel
+
+
+class AWSConfigProfile(SerializableModel):
+    def __init__(
+        self, region: Optional[str] = "us-east-1", output: Optional[str] = "json"
+    ):
+
+        self.region: Optional[str] = region
+        self.output: Optional[str] = output
+
+        self.aws_access_key_id: Optional[str] = None
+        self.aws_secret_access_key: Optional[str] = None
+        self.aws_session_token: Optional[str] = None
+
+        self.sso_session: Optional[str] = None
+        self.sso_account_id: Optional[str] = None
+        self.sso_role_name: Optional[str] = None
+
+        self.credential_process: Optional[str] = None
+        self.credential_source: Optional[str] = None
+        self.role_arn: Optional[str] = None
+        self.source_profile: Optional[str] = None
+        self.external_id: Optional[str] = None
+        self.role_session_name: Optional[str] = None
+        self.duration_seconds: Optional[str] = None
+
+
+class AWSConfigSSOSession(SerializableModel):
+    def __init__(
+        self,
+        sso_start_url: Optional[str] = None,
+        sso_region: Optional[str] = None,
+        sso_registration_scopes: Optional[str] = None,
+    ):
+        self.sso_start_url: Optional[str] = sso_start_url
+        self.sso_region: Optional[str] = sso_region
+        self.sso_registration_scopes: Optional[str] = sso_registration_scopes
+
+
+class AWSConfig:
+    """
+    Performs Operations on an AWS Config
+    """
+
+    def __init__(self):
+        pass
+
+    def get_path(self) -> Path:
+        """
+        Returns the path to the AWS config file, honoring AWS_CONFIG_FILE
+        and falling back to ~/.aws/config (or %USERPROFILE%\.aws\config on Windows).
+        """
+        # 1) Check for explicit override
+        env_path = os.environ.get("AWS_CONFIG_FILE")
+        if env_path:
+            return Path(env_path).expanduser()
+
+        # 2) Default location
+        return os.path.join(Path.home(), ".aws", "config")
+
+    def path_exists(self) -> bool:
+        path = self.get_path()
+
+        return os.path.isfile(path)
+
+    def has_profile(self, profile_name: str) -> bool:
+        config = configparser.ConfigParser()
+        self.read_section(profile_name, config)
+        return profile_name in config.sections()
+
+    def upsert_profile(
+        self,
+        name: str,
+        profile: AWSConfigProfile,
+        config_path: Optional[str] = None,
+    ):
+        self.write_section(name, profile, config_path)
+
+    def upsert_sso_session(
+        self,
+        profile_name: str,
+        sso_session: AWSConfigSSOSession,
+        profile: AWSConfigProfile | None = None,
+        config_path: Optional[str] = None,
+    ):
+        """
+        Insert / Update the SSO Session block in the aws config
+        Args:
+            Name (str): Required.  Specifies the profile name.  This is the init key
+                which is added to the section for both sso-session and profile
+                e.g. [profile {profile_name}] or [sso-session {profile_name}]
+            sso_session (AWSConfigSSOSession): Defines the values written to this session block
+            profile (AWSConfigProfile): Defines the values written to the profile block.  Typically
+                you will need a profile block along with a session block when using sso-session
+
+
+        As a general rule you will typically need to build the following:
+            [profile {profile-name}]
+            sso_session = {optionally-use-profile-name}
+            sso_account_id = {aws-acount-id}
+            sso_role_name = {sso-role}
+            region = {region}
+            output = {output}
+
+            [sso-session {profile-name}]
+            sso_start_url = {sso_start_url} e.g. https://account-alias.awsapps.com/start
+            sso_region = {region}
+            sso_registration_scopes = {scopes}
+
+        """
+
+        if not profile_name:
+            raise ValueError("Name is required")
+
+        self.write_section(profile_name, sso_session, config_path)
+
+        if profile:
+            self.write_section(profile_name, profile, config_path)
+
+    def write_section(
+        self,
+        profile_name: str | None,
+        section: AWSConfigProfile | AWSConfigSSOSession,
+        config_path: Optional[str] = None,
+    ):
+        config = configparser.ConfigParser()
+        path = config_path or self.get_path()
+
+        if self.path_exists():
+            config.read(path)  # or any INI file path
+
+        section_key = ""
+
+        if profile_name.startswith("sso-session "):
+            profile_name = profile_name.replace("sso-session ", "")
+        if profile_name.startswith("profile "):
+            profile_name = profile_name.replace("profile ", "")
+
+        if isinstance(section, AWSConfigProfile):
+            if profile_name:
+                section_key = f"profile {profile_name}"
+            else:
+                section_key = "default"
+        elif isinstance(section, AWSConfigSSOSession):
+            section_key = f"sso-session {profile_name}"
+        else:
+            raise ValueError("Invalid section type")
+
+        config = self._write_section(section_key, section, config)
+
+        with open(path, "w", encoding="utf-8") as cfg_file:
+            config.write(cfg_file)
+
+    def _write_section(
+        self,
+        section_key: str,
+        section: AWSConfigProfile | AWSConfigSSOSession,
+        config: configparser.ConfigParser,
+    ) -> configparser.ConfigParser:
+
+        # always start with a "fresh" section
+        config[section_key] = {}
+
+        section_dictionary = section.to_dictionary()
+        for key, value in section_dictionary.items():
+            if value is not None:
+                config[section_key][key] = value
+
+        return config
+
+    def read_section(
+        self,
+        profile_name: Optional[str] = None,
+        config_path: Optional[str] = None,
+        section_type: Literal["profile", "sso-session"] = "profile",
+    ) -> configparser.SectionProxy:
+        config = configparser.ConfigParser()
+        if not config_path:
+            config_path = self.get_path()
+
+        if not os.path.isfile(config_path):
+            return config
+
+        config.read(config_path)
+        profile_ini = f"{section_type} {profile_name}"
+        if profile_ini in config:
+            profile = config[profile_ini]
+            return profile
+
+        if profile_name in config:
+            profile = config[profile_name]
+            return profile
+
+        return {}

{boto3_assist-0.14.0 → boto3_assist-0.16.0}/src/boto3_assist/dynamodb/dynamodb.py

@@ -41,6 +41,8 @@ class DynamoDB(DynamoDBConnection):
         aws_access_key_id: Optional[str] = None,
         aws_secret_access_key: Optional[str] = None,
         assume_role_arn: Optional[str] = None,
+        assume_role_chain: Optional[List[str]] = None,
+        assume_role_duration_seconds: Optional[int] = 3600,
     ) -> None:
         super().__init__(
             aws_profile=aws_profile,
@@ -49,6 +51,8 @@ class DynamoDB(DynamoDBConnection):
             aws_access_key_id=aws_access_key_id,
             aws_secret_access_key=aws_secret_access_key,
             assume_role_arn=assume_role_arn,
+            assume_role_chain=assume_role_chain,
+            assume_role_duration_seconds=assume_role_duration_seconds,
         )
         self.helpers: DynamoDBHelpers = DynamoDBHelpers()
         self.log_dynamodb_item_size = (

boto3_assist-0.16.0/src/boto3_assist/dynamodb/troubleshooting.md

@@ -0,0 +1,7 @@
+
+
+1. Unable to locate credentials. You can configure credentials by running "aws configure".
+
+- out of the blue, this started happening
+- depending on how you are connecting boto3 may require a credentials file
+- running "aws configure" and simply puttting in some garbage may fix the issue.

boto3_assist-0.16.0/src/boto3_assist/session_setup_mixin.py

@@ -0,0 +1,70 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+import os
+import boto3
+from typing import Optional
+from boto3_assist.aws_config import AWSConfig
+
+
+class SessionSetupMixin:
+    def _create_base_session(
+        self,
+        aws_profile: Optional[str],
+        aws_region: Optional[str],
+        aws_access_key_id: Optional[str],
+        aws_secret_access_key: Optional[str],
+        aws_session_token: Optional[str],
+    ) -> boto3.Session:
+        try:
+            return boto3.Session(
+                profile_name=aws_profile,
+                region_name=aws_region,
+                aws_access_key_id=aws_access_key_id,
+                aws_secret_access_key=aws_secret_access_key,
+                aws_session_token=aws_session_token,
+            )
+        except Exception as e:
+
+            error_message = f"Failed to create boto3 session "
+            if "profile" in str(e).lower():
+                error_message += " due to a profile error "
+
+                error_message += f" with profile '{aws_profile}'."
+                config: AWSConfig = AWSConfig()
+                if not config.path_exists():
+                    error_message += (
+                        f" The AWS config file '{config.get_path()}' was not found. "
+                        "Please ensure that the AWS CLI is installed and configured correctly. "
+                        "You can install the AWS CLI by running 'pip install awscli' or 'pip install awscli --upgrade'. "
+                    )
+
+                    if (
+                        os.getenv("HOME") == "/tmp"
+                        or os.getenv("AWS_CONFIG_FILE") == "/tmp"
+                    ):
+                        error_message += (
+                            f'The environment HOME path is set to {os.getenv("HOME")}. '
+                        )
+                        if os.getenv("AWS_CONFIG_FILE"):
+                            error_message += (
+                                f"The environment AWS_CONFIG_FILE is set to {os.getenv('AWS_CONFIG_FILE')}. "
+                                "The AWS_CONFIG_FILE overrides the HOME directory and path. "
+                            )
+
+                        error_message += (
+                            "If you are running this locally and expecting it to be in your users home "
+                            "directory, you may need to set the HOME or AWS_CONFIG_FILE environment variable manually. "
+                            "There could be other actions such as a Lambda environment resetting the path to /tmp. "
+                            "If you are running in a GitHub Actions environment, "
+                            "you may need to set the HOME or AWS_CONFIG_FILE environment variable to '/home/runner'. "
+                        )
+                elif not config.has_profile(aws_profile):
+                    error_message += f" The profile '{aws_profile}' was not found in the AWS config file in {config.get_path()}."
+
+            # check for the existence of the profile and the path to the profile
+
+            raise RuntimeError(error_message) from e

{boto3_assist-0.14.0 → boto3_assist-0.16.0}/src/boto3_assist/utilities/serialization_utility.py

@@ -22,7 +22,7 @@ logger = Logger()
 
 
 class SerializableModel:
-    """Library to Serialize object to a DynamoDB Format"""
+    """Library to Serialize object to a DynamoDB Format or other dictionary"""
 
     T = TypeVar("T", bound="SerializableModel")
 
@@ -47,9 +47,16 @@ class SerializableModel:
 
         return mapped
 
+    def dict(self) -> Dict[str, Any]:
+        """
+        Same as .to_dictionary
+
+        """
+        return self.to_dictionary()
+
     def to_dictionary(self) -> Dict[str, Any]:
         """
-        Convert the object to a dictionary.
+        Convert the object to a dictionary. Same as .dict()
         """
         # return Serialization.convert_object_to_dict(self)
         return Serialization.to_dict(

boto3_assist-0.16.0/src/boto3_assist/version.py

@@ -0,0 +1 @@
+__version__ = '0.16.0'

boto3_assist-0.16.0/tests/unit/aws_config_test.py

@@ -0,0 +1,81 @@
+import unittest
+from pathlib import Path
+
+
+class AWSConfigTest(unittest.TestCase):
+
+    def setUp(self):
+        config_path_dir = (
+            Path(__file__).parent.joinpath(".outputs", "aws_config").resolve()
+        )
+
+        if not config_path_dir.exists():
+            config_path_dir.mkdir(parents=True, exist_ok=True)
+
+        self.config_path = config_path_dir.joinpath("config")
+
+    def test_import(self):
+        from boto3_assist.aws_config import AWSConfig
+
+        self.assertTrue(AWSConfig)
+
+    def test_init(self):
+        from boto3_assist.aws_config import AWSConfig
+        import os
+
+        aws_config = AWSConfig()
+        self.assertTrue(aws_config)
+
+    def test_path(self):
+        from boto3_assist.aws_config import AWSConfig
+        import os
+
+        aws_config = AWSConfig()
+        path = aws_config.get_path()
+
+        self.assertTrue(os.path.exists(path))
+
+    def test_config_upsert_profile(self):
+        from boto3_assist.aws_config import AWSConfig
+        from boto3_assist.aws_config import AWSConfigProfile
+
+        aws_config = AWSConfig()
+        profile = AWSConfigProfile("us-east-2", "json")
+        profile.aws_access_key_id = "111111111111"
+        profile.aws_secret_access_key = "22222222222"
+        aws_config.upsert_profile("unit-test-profile", profile)
+
+    def test_config_upsert_sso(self):
+        from boto3_assist.aws_config import AWSConfig
+        from boto3_assist.aws_config import AWSConfigSSOSession
+
+        aws_config = AWSConfig()
+        sso = AWSConfigSSOSession("us-east-1", "json")
+        sso.sso_start_url = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+        sso.sso_region = "us-east-2"
+        sso.sso_registration_scopes = "scopes"
+        aws_config.upsert_sso_session("unit-test-sso", sso)
+
+    def test_config_upsert_sso_with_profile(self):
+        from boto3_assist.aws_config import AWSConfig
+        from boto3_assist.aws_config import AWSConfigSSOSession
+        from boto3_assist.aws_config import AWSConfigProfile
+
+        aws_config = AWSConfig()
+        sso = AWSConfigSSOSession("us-east-1", "json")
+        sso.sso_start_url = "https://<account-domain>.awsapps.com/start/#/?tab=accounts"
+        sso.sso_region = "us-east-1"
+        sso.sso_registration_scopes = "sso:account:access"
+
+        section_name = "test-tenant-001"
+
+        profile = AWSConfigProfile("us-east-1", "json")
+        profile.sso_session = section_name
+        profile.sso_account_id = "AAAAAAAAAAAAAAAAAA"
+        profile.sso_role_name = "SomeRoleName"
+        profile.region = "us-east-1"
+        profile.output = "json"
+
+        aws_config.upsert_sso_session(
+            section_name, sso_session=sso, profile=profile, config_path=self.config_path
+        )

boto3_assist-0.16.0/tests/unit/session_tests/test_boto3_session_manager.py

@@ -0,0 +1,177 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from boto3 import Session as RealBoto3Session
+
+
+@pytest.fixture
+def mock_boto3_session():
+    """Patch boto3.Session and simulate a base and an assumed session with separate client behaviors."""
+    with patch("boto3.Session", autospec=True) as mock_session_class:
+        # Create base and assumed session mocks
+        base_session = MagicMock(spec=RealBoto3Session)
+        assumed_session = MagicMock(spec=RealBoto3Session)
+
+        # STS client returns mocked credentials
+        mock_sts_client = MagicMock()
+        mock_sts_client.assume_role.return_value = {
+            "Credentials": {
+                "AccessKeyId": "mock-access-key",
+                "SecretAccessKey": "mock-secret-key",
+                "SessionToken": "mock-session-token",
+            }
+        }
+
+        # Assign isolated .client behavior per session
+        base_session.client.side_effect = lambda service_name: (
+            mock_sts_client if service_name == "sts" else MagicMock()
+        )
+        assumed_session.client.return_value = MagicMock()
+
+        # Simulate two sessions: base → assumed
+        mock_session_class.side_effect = [base_session, assumed_session]
+
+        yield base_session, assumed_session, mock_sts_client, mock_session_class
+
+
+def test_single_assume_role_chain(mock_boto3_session):
+    base_session, assumed_session, mock_sts_client, session_class = mock_boto3_session
+
+    from boto3_assist.boto3session import Boto3SessionManager
+
+    manager = Boto3SessionManager(
+        service_name="s3",
+        aws_region="us-east-1",
+        assume_role_chain=["arn:aws:iam::111111111111:role/TestRole"],
+    )
+
+    # Ensure base session initialized
+    assert session_class.call_args_list[0].kwargs["region_name"] == "us-east-1"
+
+    # Ensure assume_role called correctly
+    mock_sts_client.assume_role.assert_called_once_with(
+        RoleArn="arn:aws:iam::111111111111:role/TestRole",
+        RoleSessionName="AssumeRoleSessionFors3",
+        DurationSeconds=3600,
+    )
+
+    # Ensure second session created with correct credentials
+    assert session_class.call_args_list[1].kwargs == {
+        "aws_access_key_id": "mock-access-key",
+        "aws_secret_access_key": "mock-secret-key",
+        "aws_session_token": "mock-session-token",
+        "region_name": "us-east-1",
+    }
+
+    # Ensure client created from assumed session
+    _ = manager.client
+    assumed_session.client.assert_called_with("s3", config=None, endpoint_url=None)
+
+
+def test_no_assume_role(mock_boto3_session):
+    base_session, _, _, session_class = mock_boto3_session
+
+    from boto3_assist.boto3session import Boto3SessionManager
+
+    manager = Boto3SessionManager(
+        service_name="dynamodb",
+        aws_region="us-west-2",
+    )
+
+    # Only one session created
+    assert session_class.call_count == 1
+    assert session_class.call_args.kwargs == {
+        "profile_name": None,
+        "region_name": "us-west-2",
+        "aws_access_key_id": None,
+        "aws_secret_access_key": None,
+        "aws_session_token": None,
+    }
+
+    # Resource created from base session
+    _ = manager.resource
+    base_session.resource.assert_called_with("dynamodb", config=None, endpoint_url=None)
+
+
+def test_multiple_assume_role_chain():
+    from boto3_assist.boto3session import Boto3SessionManager
+    from boto3 import Session as RealBoto3Session
+
+    with patch("boto3.Session", autospec=True) as mock_session_class:
+        # Create three sessions: base → first assume → second assume
+        base_session = MagicMock(spec=RealBoto3Session)
+        first_assumed_session = MagicMock(spec=RealBoto3Session)
+        second_assumed_session = MagicMock(spec=RealBoto3Session)
+
+        # Mock each session's client() behavior
+        first_sts = MagicMock()
+        second_sts = MagicMock()
+
+        # First assume_role returns first credentials
+        first_sts.assume_role.return_value = {
+            "Credentials": {
+                "AccessKeyId": "first-key",
+                "SecretAccessKey": "first-secret",
+                "SessionToken": "first-token",
+            }
+        }
+
+        # Second assume_role returns second credentials
+        second_sts.assume_role.return_value = {
+            "Credentials": {
+                "AccessKeyId": "second-key",
+                "SecretAccessKey": "second-secret",
+                "SessionToken": "second-token",
+            }
+        }
+
+        # Assign proper .client() behavior for each session
+        base_session.client.side_effect = lambda svc: (
+            first_sts if svc == "sts" else MagicMock()
+        )
+        first_assumed_session.client.side_effect = lambda svc: (
+            second_sts if svc == "sts" else MagicMock()
+        )
+        second_assumed_session.client.return_value = MagicMock()
+
+        # Setup session chain return order
+        mock_session_class.side_effect = [
+            base_session,
+            first_assumed_session,
+            second_assumed_session,
+        ]
+
+        # Run session manager
+        manager = Boto3SessionManager(
+            service_name="s3",
+            aws_region="us-east-1",
+            assume_role_chain=[
+                "arn:aws:iam::111111111111:role/FirstRole",
+                "arn:aws:iam::222222222222:role/SecondRole",
+            ],
+        )
+
+        # Assert role assumptions
+        first_sts.assume_role.assert_called_once_with(
+            RoleArn="arn:aws:iam::111111111111:role/FirstRole",
+            RoleSessionName="AssumeRoleSessionFors3",
+            DurationSeconds=3600,
+        )
+        second_sts.assume_role.assert_called_once_with(
+            RoleArn="arn:aws:iam::222222222222:role/SecondRole",
+            RoleSessionName="AssumeRoleSessionFors3",
+            DurationSeconds=3600,
+        )
+
+        # Assert final session creation used second credentials
+        assert mock_session_class.call_args_list[2].kwargs == {
+            "aws_access_key_id": "second-key",
+            "aws_secret_access_key": "second-secret",
+            "aws_session_token": "second-token",
+            "region_name": "us-east-1",
+        }
+
+        # Ensure client is created from final session
+        _ = manager.client
+        second_assumed_session.client.assert_called_with(
+            "s3", config=None, endpoint_url=None
+        )

boto3_assist-0.14.0/src/boto3_assist/dynamodb/troubleshooting.md

@@ -1,5 +0,0 @@
-
-
-1. Unable to locate credentials. You can configure credentials by running "aws configure".
-
-- out of the blue, this started happening

boto3_assist-0.14.0/src/boto3_assist/session_setup_mixin.py

@@ -1,29 +0,0 @@
-"""
-Geek Cafe, LLC
-Maintainers: Eric Wilson
-MIT License.  See Project Root for the license information.
-"""
-
-import boto3
-from typing import Optional
-
-
-class SessionSetupMixin:
-    def _create_base_session(
-        self,
-        aws_profile: Optional[str],
-        aws_region: Optional[str],
-        aws_access_key_id: Optional[str],
-        aws_secret_access_key: Optional[str],
-        aws_session_token: Optional[str],
-    ) -> boto3.Session:
-        try:
-            return boto3.Session(
-                profile_name=aws_profile,
-                region_name=aws_region,
-                aws_access_key_id=aws_access_key_id,
-                aws_secret_access_key=aws_secret_access_key,
-                aws_session_token=aws_session_token,
-            )
-        except Exception as e:
-            raise RuntimeError(f"Failed to create boto3 session: {e}") from e

boto3_assist-0.14.0/src/boto3_assist/version.py

@@ -1 +0,0 @@
-__version__ = '0.14.0'