boto3-assist 0.32.0__py3-none-any.whl

boto3_assist/environment_services/environment_loader.py

@@ -0,0 +1,128 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+import os
+import json
+from typing import List, Union, Optional, IO
+from pathlib import Path
+from dotenv import load_dotenv
+from aws_lambda_powertools import Logger
+
+
+logger = Logger(__name__)
+
+DEBUGGING = os.getenv("DEBUGGING", "false").lower() == "true"
+
+StrPath = Union[str, "os.PathLike[str]"]
+
+
+class EnvironmentLoader:
+    """Environment Loader"""
+
+    def __init__(self) -> None:
+        pass
+
+    def load_environment_file(
+        self,
+        *,
+        starting_path: Optional[str] = None,
+        file_name: Optional[str] = None,
+        path: Optional[StrPath] = None,
+        stream: Optional[IO[str]] = None,
+        verbose: bool = False,
+        override: bool = True,
+        interpolate: bool = True,
+        encoding: Optional[str] = "utf-8",
+        raise_error_if_not_found: bool = False,
+    ) -> bool:
+        """
+        Loads an environment file into memory. This simply passes off to load_dotenv in dotenv.
+        However one small change is that I'm defaulting override to True instead of False.
+
+
+        Args:
+            path: Absolute or relative path to .env file.
+            stream: Text stream (such as `io.StringIO`) with .env content, used if
+                `dotenv_path` is `None`.
+            verbose: Whether to output a warning the .env file is missing.
+            override: Whether to override the system environment variables with the variables
+                from the `.env` file.
+            encoding: Encoding to be used to read the file.
+        Returns:
+            Bool: True if at least one environment variable is set else False
+
+        If both `dotenv_path` and `stream` are `None`, `find_dotenv()` is used to find the
+        .env file.
+        """
+
+        if not starting_path:
+            starting_path = __file__
+
+        if file_name is None:
+            file_name = ".env"
+
+        new_path: str | StrPath | None = path or self.find_file(
+            starting_path=starting_path,
+            file_name=file_name,
+            raise_error_if_not_found=raise_error_if_not_found,
+        )
+
+        loaded = load_dotenv(
+            dotenv_path=new_path,
+            stream=stream,
+            verbose=verbose,
+            override=override,
+            interpolate=interpolate,
+            encoding=encoding,
+        )
+
+        if DEBUGGING:
+            env_vars = os.environ
+            logger.debug(f"Loaded environment file: {path}")
+            print(env_vars)
+
+        return loaded
+
+    def find_file(
+        self, starting_path: str, file_name: str, raise_error_if_not_found: bool = True
+    ) -> str | None:
+        """Searches the project directory structor for a file"""
+        parents = 10
+        starting_path = starting_path or __file__
+
+        paths: List[str] = []
+        for parent in range(parents):
+            path = Path(starting_path).parents[parent].absolute()
+            logger.debug(f"searching for {file_name} in: {path}")
+            tmp = os.path.join(path, file_name)
+            paths.append(tmp)
+            if os.path.exists(tmp):
+                return tmp
+
+        if raise_error_if_not_found:
+            searched_paths = "\n".join(paths)
+            raise RuntimeError(
+                f"Failed to locate environment file: {file_name} in: \n {searched_paths}"
+            )
+
+        return None
+
+    def load_event_file(self, full_path: str) -> dict:
+        """Loads an AWS event file"""
+        if not os.path.exists(full_path):
+            raise RuntimeError(f"Failed to locate event file: {full_path}")
+
+        event = {}
+        with open(full_path, mode="r", encoding="utf-8") as json_file:
+            event = json.load(json_file)
+
+        if isinstance(event, dict) and "message" in event:
+            event = event.get("message", {})
+
+        if isinstance(event, dict) and "event" in event:
+            event = event.get("event", {})
+
+        return event

boto3_assist/environment_services/environment_variables.py

@@ -0,0 +1,219 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+import os
+
+from aws_lambda_powertools import Logger
+
+logger = Logger(__name__)
+
+
+class EnvironmentVariables:
+    """
+    Easy access to allo the environment variables we use in the appliction.
+    It's a best practice to use this vs doing and os.getevn in each application.
+    This helps us track all the enviroment variables in use
+    """
+
+    class AWS:
+        """AWS Specific Environment Vars"""
+
+        @staticmethod
+        def region() -> str | None:
+            """
+            gets the aws region from an environment var
+            """
+            value = os.getenv("AWS_REGION")
+            if not value:
+                value = None
+            return value
+
+        @staticmethod
+        def profile() -> str | None:
+            """
+            Get the aws profile used for cli/boto3 commands
+            This should only be set with temporty creds and only for development purposes
+            """
+            value = os.getenv("AWS_PROFILE")
+            if not value:
+                value = None
+            return value
+
+        @staticmethod
+        def account_id() -> str | None:
+            """
+            gets the aws account id from an environment var
+            """
+            value = os.getenv("AWS_ACCOUNT_ID")
+            return value
+
+        @staticmethod
+        def amazon_trace_id() -> str:
+            """
+            gets the amazon trace id from an environment var
+            """
+            value = os.getenv("_X_AMZN_TRACE_ID", "NA")
+            return value
+
+        @staticmethod
+        def endpoint_url() -> str | None:
+            """
+            Gets the AWS_ENDPOINT_URL environment var
+            """
+            value = os.getenv("AWS_ENDPOINT_URL")
+            return value
+
+        @staticmethod
+        def display_aws_access_key_id() -> bool:
+            """
+            Determines if you want to display the aws access key
+            """
+            value = (
+                str(os.getenv("DISPLAY_AWS_ACCESS_KEY_ID", "false")).lower() == "true"
+            )
+            return value
+
+        @staticmethod
+        def display_aws_secret_access_key() -> bool:
+            """
+            Determines if you want to display the aws access key
+            """
+            value = (
+                str(os.getenv("DISPLAY_AWS_SECRET_ACCESS_KEY", "false")).lower()
+                == "true"
+            )
+            return value
+
+        @staticmethod
+        def aws_access_key_id() -> str | None:
+            """
+            The aws_access_key_id.  Often used for local development.
+            """
+            value = os.getenv("ACCESS_KEY_ID")
+            return value
+
+        @staticmethod
+        def aws_secret_access_key() -> str | None:
+            """
+            The aws_secret_access_key.  Often used for local development.
+            """
+            value = os.getenv("SECRET_ACCESS_KEY")
+            return value
+
+        class SES:
+            """SES Settings"""
+
+            @staticmethod
+            def user_name() -> str | None:
+                """
+                gets the ses user-name from an environment var
+                """
+                value = os.getenv("SES_USER_NAME")
+                return value
+
+            @staticmethod
+            def password() -> str | None:
+                """
+                gets the ses password from an environment var
+                """
+                value = os.getenv("SES_PASSWORD")
+                return value
+
+            @staticmethod
+            def endpoint() -> str | None:
+                """
+                gets the ses endpoint from an environment var
+                """
+                value = os.getenv("SES_END_POINT")
+                return value
+
+        class Cognito:
+            """Cognito Settings"""
+
+            @staticmethod
+            def user_pool() -> str | None:
+                """
+                gets the cognito user pool from an environment var
+                """
+                value = os.getenv("COGNITO_USER_POOL")
+                return value
+
+        class DynamoDB:
+            """DynamoDB Settings"""
+
+            @staticmethod
+            def raise_on_error_setting() -> bool:
+                """
+                determines if we raise errors on saves, gets, etc
+                this is useful to turn off for some local testing. but otherwise I
+                would recommend to leave it on
+                """
+                value = str(os.getenv("RAISE_ON_DB_ERROR", "true")).lower() == "true"
+
+                return value
+
+            @staticmethod
+            def single_table() -> str | None:
+                """
+                If a single table design is used this can be a usefull way to send it around
+                """
+                value = os.getenv("DYNAMODB_SINGLE_TABLE")
+                return value
+
+            @staticmethod
+            def endpoint_url() -> str | None:
+                """
+                The DynamoDB Endpoint url.  Often used for local development.
+                For example a docker containers defaults to http://localhost:8000
+                """
+                value = os.getenv("AWS_DYNAMODB_ENDPOINT_URL")
+                return value
+
+            @staticmethod
+            def aws_access_key_id() -> str | None:
+                """
+                The DynamoDB aws_access_key_id.  Often used for local development.
+                For example a docker containers defaults to dummy_access_key
+                """
+                value = os.getenv("AWS_DYNAMODB_ACCESS_KEY_ID")
+                return value
+
+            @staticmethod
+            def aws_secret_access_key() -> str | None:
+                """
+                The DynamoDB aws_secret_access_key.  Often used for local development.
+                For example a docker containers defaults to dummy_secret_key
+                """
+                value = os.getenv("AWS_DYNAMODB_SECRET_ACCESS_KEY")
+                return value
+
+    @staticmethod
+    def get_integration_tests_setting() -> bool:
+        """
+        deteremine if integration tests are run from an environment var
+        """
+        value = str(os.getenv("RUN_INTEGRATION_TESTS", "False")).lower() == "true"
+        env = EnvironmentVariables.get_environment_setting()
+
+        if env.lower().startswith("prod"):
+            value = False
+
+        return value
+
+    @staticmethod
+    def get_environment_setting() -> str:
+        """
+        gets the environment name from an environment var
+        """
+        value = os.getenv("ENVIRONMENT")
+
+        if not value:
+            logger.warning(
+                "ENVIRONMENT var is not set. A future version will throw an error."
+            )
+            return ""
+
+        return value

boto3_assist/erc/__init__.py

@@ -0,0 +1,64 @@
+import boto3
+from botocore.exceptions import ClientError
+from .ecr_connection import ECRConnection
+
+
+class ECR(ECRConnection):
+    pass
+
+    def retag_image(self, repository_name: str, source_tag: str, target_tag: str):
+        """
+        ReTag an ECR Image without the overhead of pulling it down, tagging and pushing.
+        Simply retags by getting the manifest, and pushing up changes.
+        Args:
+            repository_name (str):
+
+        """
+        ecr = self.client
+
+        try:
+            # 1) Get the manifest for the source tag
+            resp = ecr.batch_get_image(
+                repositoryName=repository_name,
+                imageIds=[{"imageTag": source_tag}],
+                # optional, but helps ensure you get the right manifest type:
+                acceptedMediaTypes=[
+                    "application/vnd.docker.distribution.manifest.v2+json",
+                    "application/vnd.oci.image.manifest.v1+json",
+                ],
+            )
+            images = resp.get("images", [])
+            if not images:
+                raise RuntimeError(f"No image found with tag {source_tag!r}")
+
+            manifest = images[0]["imageManifest"]
+
+            # 2) Push the same manifest under the new tag
+            put_resp = ecr.put_image(
+                repositoryName=repository_name,
+                imageManifest=manifest,
+                imageTag=target_tag,
+            )
+
+            failures = put_resp.get("failures")
+
+            if failures and len(failures) > 0:
+                raise RuntimeError(
+                    f"Failed to tag {repository_name}:{target_tag} - {failures}"
+                )
+
+            print(f"Successfully tagged {repository_name}:{target_tag}")
+            return put_resp
+
+        except ClientError as e:
+            print(
+                f"ECR error: {e.response.get('Error', {}).get('Code', 'NA')} "
+                f"- {e.response.get('Error', {}).get('Message', 'NA')}"
+            )
+            raise
+
+
+if __name__ == "__main__":
+    # Example: retag version 1.16.54 → dev
+    ecr: ECR = ECR(aws_profile="geek-cafe", aws_region="us-east-1")
+    ecr.retag_image("my-repo", "1.16.54", "dev")

boto3_assist/erc/ecr_connection.py

@@ -0,0 +1,57 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+from typing import Optional
+from typing import TYPE_CHECKING
+
+from aws_lambda_powertools import Logger
+
+from boto3_assist.connection import Connection
+
+if TYPE_CHECKING:
+    from mypy_boto3_ecr import Client
+else:
+    Client = object
+
+
+logger = Logger()
+
+
+class ECRConnection(Connection):
+    """Connection"""
+
+    def __init__(
+        self,
+        *,
+        aws_profile: Optional[str] = None,
+        aws_region: Optional[str] = None,
+        aws_end_point_url: Optional[str] = None,
+        aws_access_key_id: Optional[str] = None,
+        aws_secret_access_key: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            service_name="ecr",
+            aws_profile=aws_profile,
+            aws_region=aws_region,
+            aws_access_key_id=aws_access_key_id,
+            aws_secret_access_key=aws_secret_access_key,
+            aws_end_point_url=aws_end_point_url,
+        )
+
+        self.__client: Client | None = None
+
+    @property
+    def client(self) -> Client:
+        """Client Connection"""
+        if self.__client is None:
+            self.__client = self.session.client
+
+        return self.__client
+
+    @client.setter
+    def client(self, value: Client):
+        logger.info("Setting Client")
+        self.__client = value

boto3_assist/errors/custom_exceptions.py

@@ -0,0 +1,46 @@
+class Error(Exception):
+    """Base class for exceptions in this module."""
+
+
+class DbFailures(Error):
+    """DB Failure Error"""
+
+
+class InvalidHttpMethod(Exception):
+    """Invalid Http Method"""
+
+    def __init__(
+        self,
+        code=422,
+        message="Invalid Http Method",
+    ):
+        """The user account is not valid"""
+        self.message = {
+            "status_code": code,
+            "message": message,
+        }
+        super().__init__(self.message)
+
+
+class InvalidRoutePath(Exception):
+    """Invalid Http Route"""
+
+    def __init__(self, message="Invalid Route"):
+        """Invalid Route"""
+        self.message = {
+            "status_code": 404,
+            "message": message,
+        }
+        super().__init__(self.message)
+
+
+class FileNotFound(Exception):
+    """File Not Found Error"""
+
+    def __init__(self, message="File Not Found"):
+        """Invalid Route"""
+        self.message = {
+            "status_code": 404,
+            "message": message,
+        }
+        super().__init__(self.message)

boto3_assist/http_status_codes.py

@@ -0,0 +1,80 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+from enum import Enum
+
+
+class HttpStatusCodes(Enum):
+    """Http Status Codes"""
+
+    HTTP_400_BAD_REQUEST = 400
+    """
+    The server cannot or will not process the request due to something that is perceived to be a client error 
+    (e.g., malformed request syntax, invalid request message framing, or deceptive request routing)."""
+    HTTP_401_UNAUTHENTICATED = 401
+    """
+    Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". 
+    That is, the client must authenticate itself to get the requested response.
+    """
+    HTTP_403_FORBIDDEN = 403
+    """
+    The client does not have access rights to the content; that is, it is "unauthorized", so the server is refusing 
+    to give the requested resource. Unlike 401 Unauthorized (which is technically UnAuthenticated);
+    here, the client's identity is known to the server.
+    """
+    HTTP_404_NOT_FOUND = 404
+    """
+    The server cannot find the requested resource. In the browser, this means the URL is not recognized. 
+    In an API, this can also mean that the endpoint is valid but the resource itself does not exist. 
+    Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from 
+    an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.
+    """
+    HTTP_405_METHOD_NOT_ALLOWED = 405
+    """
+    The request method is known by the server but is not supported by the target resource. 
+    For example, an API may not allow calling DELETE to remove a resource.
+    """
+    HTTP_406_NOT_ACCEPTABLE = 406
+    """
+    This response is sent when the web server, after performing server-driven content negotiation, doesn't find any 
+    content that conforms to the criteria given by the user agent.
+    """
+    HTTP_407_PROXY_AUTHENTICATION_REQUIRED = 407
+    """
+    This is similar to 401 Unauthorized but authentication is needed to be done by a proxy.
+    """
+    HTTP_408_REQUEST_TIMEOUT = 408
+    """
+    This response is sent on an idle connection by some servers, even without any previous request by the client. 
+    It means that the server would like to shut down this unused connection. This response is used much more since 
+    some browsers, like Chrome, Firefox 27+, or IE9, use HTTP pre-connection mechanisms to speed up surfing. 
+    Also note that some servers merely shut down the connection without sending this message.
+    """
+
+    HTTP_415_UNSUPPORTED_MEDIA_TYPE = 415
+    """
+    The media format of the requested data is not supported by the server, so the server is rejecting the request.
+    """
+
+    HTTP_418_IM_A_TEAPOT = 418
+    """
+    The server refuses the attempt to brew coffee with a teapot.
+    """
+
+    HTTP_422_UNEXPECTED_OUTCOME = 422
+    """
+    The request was well-formed but was unable to be followed due to semantic errors.
+    """
+
+    HTTP_429_TOO_MANY_REQUESTS = 429
+    """
+    The user has sent too many requests in a given amount of time ("rate limiting").
+    """
+
+    HTTP_500_INTERNAL_SERVER_ERROR = 500
+    """
+    The server has encountered a situation it does not know how to handle.
+    """

boto3_assist/models/serializable_model.py

@@ -0,0 +1,9 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+from __future__ import annotations
+
+from boto3_assist.utilities.serialization_utility import SerializableModel  # noqa: F401 # pylint: disable=unused-import

boto3_assist/role_assumption_mixin.py

@@ -0,0 +1,38 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+import boto3
+from typing import List
+
+
+class RoleAssumptionMixin:
+    def _assume_roles_in_chain(
+        self,
+        base_session: boto3.Session,
+        role_chain: List[str],
+        session_name: str,
+        duration_seconds: int,
+        region: str,
+    ) -> boto3.Session:
+        session = base_session
+
+        for role_arn in role_chain:
+            sts_client = session.client("sts")
+            response = sts_client.assume_role(
+                RoleArn=role_arn,
+                RoleSessionName=session_name,
+                DurationSeconds=duration_seconds,
+            )
+            creds = response["Credentials"]
+
+            session = boto3.Session(
+                aws_access_key_id=creds["AccessKeyId"],
+                aws_secret_access_key=creds["SecretAccessKey"],
+                aws_session_token=creds["SessionToken"],
+                region_name=region,
+            )
+
+        return session