boto3-assist 0.32.0__py3-none-any.whl

boto3_assist/utilities/datetime_utility.py

@@ -0,0 +1,349 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+import uuid
+from datetime import UTC, datetime, timedelta, timezone
+from typing import Any
+import pytz  # type: ignore
+from aws_lambda_powertools import Logger
+from dateutil.relativedelta import relativedelta
+
+
+logger = Logger()
+
+_last_timestamp = None
+
+
+class DatetimeUtility:
+    @staticmethod
+    def get_elapsed_time(start: datetime, end=None) -> str:
+        end = end or DatetimeUtility.get_utc_now()
+        delta: timedelta = end - start
+
+        total_seconds = delta.total_seconds()
+        days = int(total_seconds // (3600 * 24))
+        total_seconds %= 3600 * 24
+        hours = int(total_seconds // 3600)
+        total_seconds %= 3600
+        minutes = int(total_seconds // 60)
+        seconds = int(total_seconds % 60)
+        milliseconds = int(delta.microseconds / 1000)
+        timespan = f"{days} days, {hours} hours, {minutes} minutes, {seconds} seconds, {milliseconds} milliseconds"
+
+        return timespan
+
+    @staticmethod
+    def get_start_time() -> datetime:
+        return DatetimeUtility.get_utc_now()
+
+    @staticmethod
+    def get_utc_now() -> datetime:
+        # datetime.utcnow()
+        # below is the preferred over datetime.utcnow()
+        return datetime.now(timezone.utc)
+
+    @staticmethod
+    def string_to_date(string_date: str | datetime) -> datetime | None:
+        """
+        Description: takes a string value and returns it as a datetime.
+        If the value is already a datetime type, it will return it as is, otherwise
+        the returned value is None
+        string_date: str must be in format of %Y-%m-%dT%H:%M:%S.%f
+        """
+
+        if not string_date or str(string_date) == "None":
+            return None
+
+        if isinstance(string_date, datetime):
+            return string_date
+
+        if "Z" in str(string_date):
+            string_date = str(string_date).replace("Z", "+00:00")
+        string_date = str(string_date)
+        string_date = string_date.replace(" ", "T")
+        string_date = string_date.replace("Z", "")
+        string_date = string_date.replace("+00:00", "")
+        # todo determine the format
+        date_formats = [
+            "%Y-%m-%dT%H:%M:%S.%f",
+            "%Y-%m-%dT%H:%M:%S",
+            "%Y-%m-%d",
+            "%m-%d-%Y",
+            "%m-%d-%y",
+            "%Y/%m/%d",
+            "%m/%d/%Y",
+            "%m/%d/%y",
+        ]
+
+        result: datetime | None = None
+        try:
+            if isinstance(string_date, str):
+                for date_format in date_formats:
+                    try:
+                        result = datetime.strptime(string_date, date_format)
+                        break
+                    except ValueError:
+                        pass
+                # if nothing the we need to raise an error
+                if result is None:
+                    raise ValueError(f"Unable to parse date: {string_date}")
+
+            elif isinstance(string_date, datetime):
+                result = string_date
+            else:
+                logger.warning(
+                    {
+                        "metric_filter": "string_to_date_warning",
+                        "datetime": string_date,
+                        "action": "returning none",
+                    }
+                )
+        except Exception as e:  # noqa: E722, pylint: disable=W0718
+            msg = {
+                "metric_filter": "string_to_date_error",
+                "datetime": string_date,
+                "error": str(e),
+                "action": "returning none",
+                "type": type(string_date).__name__,
+                "accepted_formats": date_formats,
+            }
+            logger.error(msg=msg)
+
+            raise RuntimeError(msg) from e
+
+        return result
+
+    @staticmethod
+    def to_datetime(
+        value, default: datetime | None = None, tzinfo=UTC
+    ) -> datetime | None:
+        """
+        Description: takes a value and attempts to turn it into a datetime object
+        Returns: datetime or None
+        """
+
+        result = DatetimeUtility.string_to_date(value)
+
+        if result is None and default is not None:
+            if not isinstance(default, datetime):
+                default = DatetimeUtility.string_to_date(value)
+            result = default
+
+        if result and isinstance(result, datetime):
+            result = result.replace(tzinfo=tzinfo)
+
+        return result
+
+    @staticmethod
+    def to_datetime_utc(value, default: datetime | None = None) -> datetime | None:
+        """
+        Description: takes a value and attempts to turn it into a datetime object
+        Returns: datetime or None
+        """
+
+        result = DatetimeUtility.to_datetime(value, default, tzinfo=UTC)
+        return result
+
+    @staticmethod
+    def to_date_string(value: Any, default: datetime | None | str = None) -> str | None:
+        """
+        Description: takes a value and attempts to turn it into a datetime object
+        Returns: datetime or None
+        """
+        value = DatetimeUtility.to_datetime(value=value)
+        result = DatetimeUtility.to_string(value, date_format="%Y-%m-%d")
+        if result is None and default is not None:
+            if isinstance(default, datetime):
+                result = DatetimeUtility.to_string(default, date_format="%Y-%m-%d")
+
+        return result
+
+    @staticmethod
+    def to_time_string(value, default: datetime | None = None) -> str | None:
+        """
+        Description: takes a value and attempts to turn it into a datetime object
+        Returns: datetime or None
+        """
+        value = DatetimeUtility.to_datetime(value=value)
+        result = f"{DatetimeUtility.to_string(value, date_format='%H:%M:%S')}+00:00"
+        if result is None and default is not None:
+            result = default
+
+        return result
+
+    @staticmethod
+    def to_string(
+        value: datetime, date_format: str = "%Y-%m-%d-%H-%M-%S-%f"
+    ) -> str | None:
+        """
+        Description: takes a string value and returns it as a datetime.
+        If the value is already a datetime type, it will return it as is, otherwise
+        the returned value is None
+        """
+        # todo determine the format
+        if not value:
+            return None
+
+        result = value.strftime(date_format)
+
+        return result
+
+    @staticmethod
+    def datetime_from_uuid1(uuid1: uuid.UUID) -> datetime:
+        """
+        Converts a uuid1 to a datetime
+        """
+        ns = 0x01B21DD213814000
+        timestamp = datetime.fromtimestamp(
+            (uuid1.time - ns) * 100 / 1e9, tz=timezone.utc
+        )
+        return timestamp
+
+    @staticmethod
+    def fromtimestamp(value: float, default=None) -> datetime:
+        result = default
+        try:
+            if "-" in str(value):
+                value = float(str(value).replace("-", "."))
+            result = datetime.fromtimestamp(float(value))
+        except Exception as e:
+            logger.error(str(e))
+            pass
+
+        return result
+
+    @staticmethod
+    def uuid1_utc(node=0, clock_seq=0, timestamp=None):
+        global _last_timestamp  # pylint: disable=w0603
+
+        if not timestamp:
+            timestamp = float(DatetimeUtility.get_utc_now().timestamp())
+        if isinstance(timestamp, datetime):
+            timestamp = timestamp.timestamp()
+
+        nanoseconds = int(timestamp * 1e9)
+        # import time
+        # t = time.time_ns()
+        # ns = int(t * 1e9)
+
+        # 0x01b21dd213814000 is the number of 100-ns intervals between the
+        # UUID epoch 1582-10-15 00:00:00 and the Unix epoch 1970-01-01 00:00:00.
+        timestamp = nanoseconds // 100 + 0x01B21DD213814000
+        if _last_timestamp is not None and timestamp <= _last_timestamp:
+            timestamp = _last_timestamp + 1
+        _last_timestamp = timestamp
+        if clock_seq is None:
+            import random
+
+            clock_seq = random.getrandbits(14)  # instead of stable storage
+        time_low = timestamp & 0xFFFFFFFF
+        time_mid = (timestamp >> 32) & 0xFFFF
+        time_hi_version = (timestamp >> 48) & 0x0FFF
+        clock_seq_low = clock_seq & 0xFF
+        clock_seq_hi_variant = (clock_seq >> 8) & 0x3F
+        if node is None:
+            node = uuid.getnode()
+        return uuid.UUID(
+            fields=(
+                time_low,
+                time_mid,
+                time_hi_version,
+                clock_seq_hi_variant,
+                clock_seq_low,
+                node,
+            ),
+            version=1,
+        )
+
+    @staticmethod
+    def add_month(dt: datetime, months: int = 1) -> datetime:
+        """Add a month to the current date
+
+        Args:
+            dt (datetime): datetime
+            months (int): the number of months
+
+        Returns:
+            datetime: X Month(s) added to the input dt
+        """
+        new_date = dt + relativedelta(months=+months)
+        new_date = new_date + relativedelta(microseconds=-1)
+
+        return new_date
+
+    @staticmethod
+    def add_days(dt: datetime, days: int = 1) -> datetime:
+        """Add a day to the current date
+
+        Args:
+            dt (datetime): datetime
+            days (int): the number of days, use a negative number to subtract
+
+        Returns:
+            datetime: X days added to the input dt
+        """
+        new_date = dt + relativedelta(days=+days)
+        new_date = new_date + relativedelta(microseconds=-1)
+
+        return new_date
+
+    @staticmethod
+    def add_minutes(dt: datetime, minutes: int = 1) -> datetime:
+        """Add a month to the current date
+
+        Args:
+            dt (datetime): datetime
+            months (int): the number of months
+
+        Returns:
+            datetime: One Month added to the input dt
+        """
+        new_date = dt + relativedelta(minutes=+minutes)
+        new_date = new_date + relativedelta(microseconds=-1)
+
+        return new_date
+
+    @staticmethod
+    def to_timezone(utc_datetime: datetime, timezone_name: str) -> datetime:
+        """_summary_
+
+        Args:
+            utc_datetime (datetime): datetime in utc
+            timezone (str): 'US/Eastern', 'US/Mountain', etc
+
+        Returns:
+            datetime: in the correct timezone
+        """
+
+        tz = pytz.timezone(timezone_name)
+        result = utc_datetime.astimezone(tz)
+        return result
+
+    @staticmethod
+    def get_timestamp(value: datetime | None | str) -> float:
+        """Get a timestamp from a date or 0.0"""
+        if value is None:
+            return 0.0
+        if not isinstance(value, datetime):
+            value = DatetimeUtility.to_datetime_utc(value=value)
+
+        if not isinstance(value, datetime):
+            return 0.0
+        ts = value.timestamp()
+        return ts
+
+    @staticmethod
+    def get_timestamp_or_none(value: datetime | None | str) -> float | None:
+        """Get a timestamp from a date or None"""
+        if value is None:
+            return None
+        if not isinstance(value, datetime):
+            value = DatetimeUtility.to_datetime_utc(value=value)
+
+        if not isinstance(value, datetime):
+            return None
+        ts = value.timestamp()
+        return ts

boto3_assist/utilities/decimal_conversion_utility.py

@@ -0,0 +1,140 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+from decimal import Decimal
+from typing import Any, Dict, List, Union
+
+
+class DecimalConversionUtility:
+    """
+    Utility class for handling decimal conversions between Python types and DynamoDB.
+    
+    DynamoDB stores all numbers as Decimal types, but Python applications often
+    expect int or float types. This utility provides conversion methods to handle
+    the transformation seamlessly.
+    """
+
+    @staticmethod
+    def convert_decimals_to_native_types(data: Any) -> Any:
+        """
+        Recursively converts Decimal objects to native Python types (int or float).
+        
+        This is typically used when deserializing data from DynamoDB, where all
+        numbers are stored as Decimal objects but the application expects native
+        Python numeric types.
+        
+        Args:
+            data: The data structure to convert. Can be dict, list, or any other type.
+            
+        Returns:
+            The data structure with Decimal objects converted to int or float.
+        """
+        if isinstance(data, dict):
+            return {
+                key: DecimalConversionUtility.convert_decimals_to_native_types(value)
+                for key, value in data.items()
+            }
+        elif isinstance(data, list):
+            return [
+                DecimalConversionUtility.convert_decimals_to_native_types(item)
+                for item in data
+            ]
+        elif isinstance(data, Decimal):
+            # Convert Decimal to int if it's a whole number, otherwise to float
+            if data % 1 == 0:
+                return int(data)
+            else:
+                return float(data)
+        else:
+            return data
+
+    @staticmethod
+    def convert_native_types_to_decimals(data: Any) -> Any:
+        """
+        Recursively converts native Python numeric types (int, float) to Decimal objects.
+        
+        This is typically used when serializing data for DynamoDB, where all
+        numbers should be stored as Decimal objects for precision.
+        
+        Args:
+            data: The data structure to convert. Can be dict, list, or any other type.
+            
+        Returns:
+            The data structure with int and float objects converted to Decimal.
+        """
+        if isinstance(data, dict):
+            return {
+                key: DecimalConversionUtility.convert_native_types_to_decimals(value)
+                for key, value in data.items()
+            }
+        elif isinstance(data, list):
+            return [
+                DecimalConversionUtility.convert_native_types_to_decimals(item)
+                for item in data
+            ]
+        elif isinstance(data, float):
+            # Convert float to Decimal using string representation for precision
+            return Decimal(str(data))
+        elif isinstance(data, int) and not isinstance(data, bool):
+            # Convert int to Decimal, but exclude bool (which is a subclass of int)
+            return Decimal(data)
+        else:
+            return data
+
+    @staticmethod
+    def is_numeric_type(value: Any) -> bool:
+        """
+        Check if a value is a numeric type (int, float, or Decimal).
+        
+        Args:
+            value: The value to check.
+            
+        Returns:
+            True if the value is a numeric type, False otherwise.
+        """
+        return isinstance(value, (int, float, Decimal)) and not isinstance(value, bool)
+
+    @staticmethod
+    def safe_decimal_conversion(value: Any, default: Any = None) -> Union[Decimal, Any]:
+        """
+        Safely convert a value to Decimal, returning a default if conversion fails.
+        
+        Args:
+            value: The value to convert to Decimal.
+            default: The default value to return if conversion fails.
+            
+        Returns:
+            Decimal representation of the value, or the default if conversion fails.
+        """
+        try:
+            if isinstance(value, Decimal):
+                return value
+            elif isinstance(value, (int, float)):
+                return Decimal(str(value))
+            elif isinstance(value, str):
+                return Decimal(value)
+            else:
+                return default
+        except (ValueError, TypeError, ArithmeticError):
+            return default
+
+    @staticmethod
+    def format_decimal_for_display(value: Decimal, precision: int = 2) -> str:
+        """
+        Format a Decimal value for display with specified precision.
+        
+        Args:
+            value: The Decimal value to format.
+            precision: Number of decimal places to display.
+            
+        Returns:
+            Formatted string representation of the Decimal.
+        """
+        if not isinstance(value, Decimal):
+            value = DecimalConversionUtility.safe_decimal_conversion(value, Decimal('0'))
+        
+        format_string = f"{{:.{precision}f}}"
+        return format_string.format(float(value))

boto3_assist/utilities/dictionary_utility.py

@@ -0,0 +1,32 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+from typing import List
+
+
+class DictionaryUtilitiy:
+    """
+    A class to provide utility methods for working with dictionaries.
+    """
+
+    @staticmethod
+    def find_dict_by_name(
+        dict_list: List[dict], key_field: str, name: str
+    ) -> List[dict] | dict | str:
+        """
+        Searches for dictionaries in a list where the key 'name' matches the specified value.
+
+        Args:
+        dict_list (list): A list of dictionaries to search through.
+        key_field (str): The key to search for in each dictionary.
+        name (str): The value to search for in the 'key_field' key.
+
+        Returns:
+        list: A list of dictionaries where the 'key_field' key matches the specified value.
+        """
+        # List comprehension to filter dictionaries that have the 'name' key equal to the specified name
+
+        return [d for d in dict_list if d.get(key_field) == name]

boto3_assist/utilities/file_operations.py

@@ -0,0 +1,135 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+import os
+
+import shutil
+import tempfile
+
+
+from aws_lambda_powertools import Logger
+
+logger = Logger()
+
+
+class FileOperations:
+    """
+    General File Operations
+    """
+
+    def __init__(self) -> None:
+        pass
+
+    @staticmethod
+    def makedirs(path):
+        """Create a directory and all sub directories."""
+        abs_path = os.path.abspath(path)
+        os.makedirs(abs_path, exist_ok=True)
+
+    @staticmethod
+    def clean_directory(path: str):
+        """Clean / Delete all files and directories and sub directories"""
+        if path is None:
+            return
+        if path == "/":
+            raise ValueError("Cannot delete root directory")
+
+        abs_path = os.path.abspath(path)
+        if os.path.exists(abs_path):
+            items = os.listdir(abs_path)
+            for item in items:
+                path = os.path.join(abs_path, item)
+                if os.path.exists(path):
+                    try:
+                        if os.path.isdir(path):
+                            shutil.rmtree(path)
+                        elif os.path.isfile(path):
+                            os.remove(path)
+
+                    except Exception as e:  # pylint: disable=W0718
+                        logger.exception(f"clean up error {str(e)}")
+
+    @staticmethod
+    def get_directory_name(path: str):
+        """
+        Get the directory path from a path that is either a directory
+        or a path to a file.
+        """
+        dirname = os.path.dirname(path)
+        return dirname
+
+    @staticmethod
+    def read_file(path: str, encoding: str = "utf-8") -> str:
+        """
+        Read a file
+        """
+        logger.debug(f"reading file {path}")
+        with open(path, "r", encoding=encoding) as file:
+            data = file.read()
+        return data
+
+    @staticmethod
+    def write_to_file(path: str, data: str, append: bool = False) -> str:
+        """
+        Write to a file
+
+        """
+        return FileOperations.write_file(path=path, output=data, append=append)
+
+    @staticmethod
+    def write_file(path: str, output: str, append: bool = False) -> str:
+        """
+        Writes to a file
+        Args:
+            path (str): path
+            output (str): text to write to the file
+            append (bool): if true this operation will append to the file
+                otherwise it will overwrite. the default is to overwrite
+        Returns:
+            str: path to the file
+        """
+        dirname = FileOperations.get_directory_name(path)
+        FileOperations.makedirs(dirname)
+        mode = "a" if append else "w"
+
+        if output is None:
+            output = ""
+        with open(path, mode=mode, encoding="utf-8") as file:
+            file.write(output)
+
+        return path
+
+    @staticmethod
+    def get_file_extension(file_name: str, include_dot: bool = False):
+        """Get the extension of a file"""
+        logger.debug(f"getting extension for {file_name}")
+        # get the last part of a string after a period .
+        extention = os.path.splitext(file_name)[1]
+        logger.debug(f"extention is {extention}")
+
+        if not include_dot:
+            if str(extention).startswith("."):
+                extention = str(extention).removeprefix(".")
+                logger.debug(f"extension after prefix removal: {extention}")
+
+        return extention
+
+    @staticmethod
+    def get_tmp_directory() -> str:
+        """
+        Get the temp directory
+        """
+        # are we in an aws lambda function?
+        if os.environ.get("AWS_LAMBDA_FUNCTION_NAME"):
+            # we are in a lambda function /tmp is the only place
+            # we can write to
+            if not os.path.exists("/tmp"):
+                raise ValueError("Temp directory does not exist.")
+
+            tmp_dir = "/tmp"
+            return tmp_dir
+
+        return tempfile.gettempdir()

boto3_assist/utilities/http_utility.py

@@ -0,0 +1,48 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+from urllib.parse import unquote
+from typing import Dict, Any
+
+
+class HttpUtility:
+    """HTTP Utilities"""
+
+    @staticmethod
+    def get_query_params(query_string: str) -> Dict[str, Any]:
+        """
+        Get the query parameters from a query string
+        returns a dictionary of key value pairs
+        """
+        if not query_string:
+            return {}
+
+        params = {}
+        if query_string:
+            for param in query_string.split("&"):
+                key, value = param.split("=")
+                params[key] = unquote(value)
+        return params
+
+    @staticmethod
+    def get_query_param(query_string: str | None, key: str) -> str | None:
+        """Get a query parameter from a query string"""
+
+        if not query_string:
+            return None
+        params = HttpUtility.get_query_params(query_string)
+        if key in params:
+            return params[key]
+        return None
+
+    @staticmethod
+    def decode_url(url: str):
+        """Decodes a URL"""
+
+        # sometimes a paylaod will have a + added instead of the space
+        # or the space encoded value of %2B
+        url = url.replace("+", " ")
+        return unquote(url)