boto3-assist 0.20.0__py3-none-any.whl → 0.22.0__py3-none-any.whl

boto3_assist/dynamodb/dynamodb.py

@@ -6,6 +6,8 @@ MIT License.  See Project Root for the license information.
 
 import os
 from typing import List, Optional, overload, Dict, Any
+from botocore.exceptions import ClientError
+from boto3.dynamodb.conditions import Attr
 
 from aws_lambda_powertools import Logger
 from boto3.dynamodb.conditions import (
@@ -65,17 +67,22 @@ class DynamoDB(DynamoDBConnection):
         item: dict | DynamoDBModelBase,
         table_name: str,
         source: Optional[str] = None,
+        fail_if_exists: bool = False,
     ) -> dict:
         """
         Save an item to the database
         Args:
-            item (dict): DynamoDB Dictionary Object or DynamoDBModelBase.  Supports the "client" or
-            "resource" syntax
+            item (dict): DynamoDB Dictionary Object or DynamoDBModelBase.
+                Supports the "client" or "resource" syntax
             table_name (str): The DynamoDb Table Name
             source (str, optional): The source of the call, used for logging. Defaults to None.
+            fail_if_exists (bool, optional): Only allow it to insert once.
+                Fail if it already exits. This is useful for loggers, historical records,
+                tasks, etc. that should only be created once
 
         Raises:
-            e: Any Error Raised
+            ClientError: Client specific errors
+            Exception: Any Error Raised
 
         Returns:
             dict: The Response from DynamoDB's put_item actions.
@@ -85,7 +92,7 @@ class DynamoDB(DynamoDBConnection):
 
         try:
             if not isinstance(item, dict):
-                # attemp to convert it
+                # attempt to convert it
                 if not isinstance(item, DynamoDBModelBase):
                     raise RuntimeError(
                         f"Item is not a dictionary or DynamoDBModelBase. Type: {type(item).__name__}. "
@@ -106,19 +113,49 @@ class DynamoDB(DynamoDBConnection):
 
             if isinstance(item, dict) and isinstance(next(iter(item.values())), dict):
                 # Use boto3.client syntax
-                response = dict(
-                    self.dynamodb_client.put_item(TableName=table_name, Item=item)
-                )
+                # client API style
+                params = {
+                    "TableName": table_name,
+                    "Item": item,
+                }
+                if fail_if_exists:
+                    # only insert if the item does *not* already exist
+                    params["ConditionExpression"] = (
+                        "attribute_not_exists(#pk) AND attribute_not_exists(#sk)"
+                    )
+                    params["ExpressionAttributeNames"] = {"#pk": "pk", "#sk": "sk"}
+                response = dict(self.dynamodb_client.put_item(**params))
+
             else:
                 # Use boto3.resource syntax
                 table = self.dynamodb_resource.Table(table_name)
-                response = dict(table.put_item(Item=item))  # type: ignore[arg-type]
+                if fail_if_exists:
+                    cond = Attr("pk").not_exists() & Attr("sk").not_exists()
+                    response = dict(table.put_item(Item=item, ConditionExpression=cond))
+                else:
+                    response = dict(table.put_item(Item=item))
+                    # response = dict(table.put_item(Item=item))  # type: ignore[arg-type]
+
+        except ClientError as e:
+            if (
+                fail_if_exists
+                and e.response["Error"]["Code"] == "ConditionalCheckFailedException"
+            ):
+                raise RuntimeError(
+                    f"Item with pk={item['pk']} already exists in {table_name} "
+                    f"and fail_if_exists was set to {fail_if_exists}"
+                ) from e
+
+            logger.exception(
+                {"source": f"{source}", "metric_filter": "put_item", "error": str(e)}
+            )
+            raise
 
         except Exception as e:  # pylint: disable=w0718
             logger.exception(
                 {"source": f"{source}", "metric_filter": "put_item", "error": str(e)}
             )
-            raise e
+            raise
 
         return response
 

boto3_assist/dynamodb/dynamodb_key.py

@@ -49,7 +49,52 @@ class DynamoDBKey:
     def build_key(*key_value_pairs) -> str:
         """
         Static method to build a key based on provided key-value pairs.
-        Stops appending if any value is None.
+        - Stops appending if any value is None.
+        - However a value of "" (empty string) will continue the chain.
+
+        Example:
+            gsi.partition_key.value = lambda: DynamoDBKey.build_key(
+                ("user",self.model.user_id)
+            )
+
+            pk: user#<user-id>
+            pk: user#123456789
+
+            gsi.sort_key.value = lambda: DynamoDBKey.build_key(
+                ("xref", self.model.xref_type),
+                ("id", self.model.xref_pk),
+
+            )
+
+            sk: xref#<xref-type>#id#<some-id>
+            sk: xref#task#id#123456789
+
+            # example two has a leading "domain" (crm)
+            gsi.sort_key.value = lambda: DynamoDBKey.build_key(
+                ("crm", "")
+                ("xref", self.model.xref_type),
+                ("id", self.model.xref_pk),
+
+            )
+
+            sk: crm#xref#<xref-type>#id#<some-id>
+            sk: crm#xref#task#id#123456789
+
+            # using None stops the key build
+            # useful when doing begins with
+
+            # assume self.model.xref_pk is None
+            gsi.sort_key.value = lambda: DynamoDBKey.build_key(
+                ("xref", self.model.xref_type),
+                ("id", self.model.xref_pk),
+
+            )
+            # results with a key of
+            # which would get all of the users tasks assuming the pk was still
+            # the same
+            sk: xref#<xref-type>#id#
+            sk: xref#task#id#
+
         """
         parts = []
         for key, value in key_value_pairs:
@@ -57,6 +102,8 @@ class DynamoDBKey:
             if value is None:
                 parts.append(f"{prefix}")
                 break
+            elif len(str(value).strip()) == 0:
+                parts.append(f"{key}")
             else:
                 parts.append(f"{prefix}{value}")
         key_str = "#".join(parts)

boto3_assist/dynamodb/dynamodb_model_base_interfaces.py

@@ -25,10 +25,10 @@ class HasKeys(Protocol):
     """Interface for classes that have primary and sort keys"""
 
     def get_pk(self, index_name: str) -> Optional[str]:
-        """Inteface to get_pk"""
+        """Interface to get_pk"""
 
     def get_sk(self, index_name: str) -> Optional[str]:
-        """Inteface to get_sk"""
+        """Interface to get_sk"""
 
     def get_key(self, index_name: str) -> And | Equals:
         """Get the index name and key"""

boto3_assist/utilities/datetime_utility.py

@@ -12,7 +12,6 @@ from aws_lambda_powertools import Logger
 from dateutil.relativedelta import relativedelta
 
 
-
 logger = Logger()
 
 _last_timestamp = None
@@ -43,11 +42,10 @@ class DatetimeUtility:
     @staticmethod
     def get_utc_now() -> datetime:
         # datetime.utcnow()
-        # below is the prefered over 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.
@@ -269,7 +267,7 @@ class DatetimeUtility:
             months (int): the number of months
 
         Returns:
-            datetime: One Month added to the input dt
+            datetime: X Month(s) added to the input dt
         """
         new_date = dt + relativedelta(months=+months)
         new_date = new_date + relativedelta(microseconds=-1)
@@ -278,14 +276,14 @@ class DatetimeUtility:
 
     @staticmethod
     def add_days(dt: datetime, days: int = 1) -> datetime:
-        """Add a month to the current date
+        """Add a day to the current date
 
         Args:
             dt (datetime): datetime
-            months (int): the number of months
+            days (int): the number of days, use a negative number to subtract
 
         Returns:
-            datetime: One Month added to the input dt
+            datetime: X days added to the input dt
         """
         new_date = dt + relativedelta(days=+days)
         new_date = new_date + relativedelta(microseconds=-1)
@@ -314,7 +312,7 @@ class DatetimeUtility:
 
         Args:
             utc_datetime (datetime): datetime in utc
-            timezone (str): 'US/Eastern', 'US/Moutain', etc
+            timezone (str): 'US/Eastern', 'US/Mountain', etc
 
         Returns:
             datetime: in the correct timezone
@@ -326,7 +324,7 @@ class DatetimeUtility:
 
     @staticmethod
     def get_timestamp(value: datetime | None | str) -> float:
-        """Get a timestampe from a date or 0.0"""
+        """Get a timestamp from a date or 0.0"""
         if value is None:
             return 0.0
         if not isinstance(value, datetime):
@@ -339,7 +337,7 @@ class DatetimeUtility:
 
     @staticmethod
     def get_timestamp_or_none(value: datetime | None | str) -> float | None:
-        """Get a timestampe from a date or None"""
+        """Get a timestamp from a date or None"""
         if value is None:
             return None
         if not isinstance(value, datetime):

boto3_assist/version.py

@@ -1 +1 @@
-__version__ = '0.20.0'
+__version__ = '0.22.0'

{boto3_assist-0.20.0.dist-info → boto3_assist-0.22.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boto3_assist
-Version: 0.20.0
+Version: 0.22.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.20.0.dist-info → boto3_assist-0.22.0.dist-info}/RECORD

@@ -6,7 +6,7 @@ boto3_assist/connection_tracker.py,sha256=UgfR9RlvXf3A4ssMr3gDMpw89ka8mSRvJn4M34
 boto3_assist/http_status_codes.py,sha256=G0zRSWenwavYKETvDF9tNVUXQz3Ae2gXdBETYbjvJe8,3284
 boto3_assist/role_assumption_mixin.py,sha256=PMUU5yC2FUBjFD1UokVkRY3CPB5zTw85AhIB5BMtbc8,1031
 boto3_assist/session_setup_mixin.py,sha256=X-JQKyyaWNA8Z8kKgf2V2I5vsiLAH8udLTX_xepnsdQ,3140
-boto3_assist/version.py,sha256=pJLteH9r0aOnAwnvPatmr2QSz7lO2BDXON0AKkXx0Pg,23
+boto3_assist/version.py,sha256=h1iZs_ySY6is5xPKVypDpl9q8RFwvTXfv3Urt9ZSKSQ,23
 boto3_assist/aws_lambda/event_info.py,sha256=OkZ4WzuGaHEu_T8sB188KBgShAJhZpWASALKRGBOhMg,14648
 boto3_assist/aws_lambda/mock_context.py,sha256=LPjHP-3YSoY6iPl1kPqJDwSVf1zLNTcukUunDtYcbK0,116
 boto3_assist/cloudwatch/cloudwatch_connection.py,sha256=mnGWaLSQpHh5EeY7Ek_2o9JKHJxOELIYtQVMX1IaHn4,2480
@@ -19,15 +19,15 @@ boto3_assist/cognito/cognito_connection.py,sha256=deuXR3cNHz0mCYff2k0LfAvK--9Okq
 boto3_assist/cognito/cognito_utility.py,sha256=IVZAg58nHG1U7uxe7FsTYpqwwZiwwdIBGiVTZuLCFqg,18417
 boto3_assist/cognito/jwks_cache.py,sha256=1Y9r-YfQ8qrgZN5xYPvjUEEV0vthbdcPdAIaPbZP7kU,373
 boto3_assist/cognito/user.py,sha256=qc44qLx3gwq6q2zMxcPQze1EjeZwy5Kuav93vbe-4WU,820
-boto3_assist/dynamodb/dynamodb.py,sha256=zq2Hqhmd3aXjnd1GAmYq5TkjMPiq_pHcMW6hClSv13Y,16679
+boto3_assist/dynamodb/dynamodb.py,sha256=2Xg9_aqcXzZm-4hASt6Z-mCR0gSs6iUDzLdAqzPn81o,18370
 boto3_assist/dynamodb/dynamodb_connection.py,sha256=D4KmVpMpE0OuVOwW5g4JBWllUNkwy0hMXEGUiToAMBc,3608
 boto3_assist/dynamodb/dynamodb_helpers.py,sha256=RoRRqKjdwfC-2-gvlkLvCoNWhIoMrHm-68dkyhXI_Xk,12080
 boto3_assist/dynamodb/dynamodb_importer.py,sha256=nCKsyRQeMqDSf0Q5mQ_X_oVIg4PRnu0hcUzZnBli610,3471
 boto3_assist/dynamodb/dynamodb_index.py,sha256=D0Lq121qk1cXeMetPeqnzvv6CXd0XfEygfdUXaljLG8,8551
 boto3_assist/dynamodb/dynamodb_iservice.py,sha256=O9Aj0PFEvcuk2vhARifWTFnUwcQW5EXzwZS478Hm-N0,796
-boto3_assist/dynamodb/dynamodb_key.py,sha256=YD7o1EUlwVBQ55p9YCTKqAUU_np4nqtLIHnmp-BeolM,1803
+boto3_assist/dynamodb/dynamodb_key.py,sha256=4IYnG4a99AjdOKUcDaWhNF_lvZJRZcKOIPzBQQzVdB0,3294
 boto3_assist/dynamodb/dynamodb_model_base.py,sha256=ceVKmequ2S7zY-8IkQwmtNvGV8GtaEraFBy1c2Y5P4A,12031
-boto3_assist/dynamodb/dynamodb_model_base_interfaces.py,sha256=yT4zDRI8vP15WVOHnCvY3FsEy_QSIta5-bnUby70Xow,747
+boto3_assist/dynamodb/dynamodb_model_base_interfaces.py,sha256=SFw-yK7TDPL4cK52bpn2zMm5G4mX7eYNU7eFytEw0-A,749
 boto3_assist/dynamodb/dynamodb_re_indexer.py,sha256=Y0qRrvpmjS68w8ci6Au7Hg02W_ktqhUGGALeN-9XTls,6164
 boto3_assist/dynamodb/dynamodb_reindexer.py,sha256=bCj6KIU0fQOgjkkiq9yF51PFZZr4Y9Lu3-hPlmsPG0Y,6164
 boto3_assist/dynamodb/dynamodb_reserved_words.py,sha256=p0irNBSqGe4rd2FwWQqbRJWrNr4svdbWiyIXmz9lj4c,1937
@@ -49,7 +49,7 @@ boto3_assist/securityhub/securityhub.py,sha256=ne-J_v4DaCVZm5YgJa_-LKVomLJQo5Gpw
 boto3_assist/securityhub/securityhub_connection.py,sha256=hWfcj9gjS2lNXUObyw4cShtveoqJPIp8kKFuz-fz1J4,1449
 boto3_assist/ssm/connection.py,sha256=gYpKn5HsUR3hcRUqJzF5QcTITCk0DReq9KhoE_8-Htg,1370
 boto3_assist/ssm/parameter_store/parameter_store.py,sha256=2ISi-SmR29mESHFH-onJkxPX1aThIgBRojA3ZoNcP9s,3949
-boto3_assist/utilities/datetime_utility.py,sha256=kxUV-pYraTx18gaRb2LxXB7sRTBxffgksdOszcM3fg8,11150
+boto3_assist/utilities/datetime_utility.py,sha256=yQa9winN661Gt837zeQQWl4ARMYtZcU4pQEYMnTESC0,11171
 boto3_assist/utilities/dictionary_utility.py,sha256=IrN5Q3gJ_KWQ_3KCjyXEJyV8oLk2n3tQOO52dVbY6sk,1002
 boto3_assist/utilities/file_operations.py,sha256=IYhJkh8wUPMvGnyDRRa9yOCDdHN9wR3N6m_xpJS51TM,3949
 boto3_assist/utilities/http_utility.py,sha256=_K39Fq0V4QcgklAWctUktuMjqXDTwgMld77IOUfR2zc,1282
@@ -57,8 +57,8 @@ boto3_assist/utilities/logging_utility.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5N
 boto3_assist/utilities/numbers_utility.py,sha256=wzv9d0uXT_2_ZHHio7LBzibwxPqhGpvbq9HinrVn_4A,10160
 boto3_assist/utilities/serialization_utility.py,sha256=Jc6H0cpcZjLO7tdyUZdBWHzItduLkw6sh2YQh8Hc8D8,21647
 boto3_assist/utilities/string_utility.py,sha256=XxUIz19L2LFFTRDAAmdPa8Qhn40u9yO7g4nULFuvg0M,11033
-boto3_assist-0.20.0.dist-info/METADATA,sha256=fTDDcy1YzJ4vDZFqic4B1-veECbBopRgj9Yyj0FTeEI,2875
-boto3_assist-0.20.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-boto3_assist-0.20.0.dist-info/licenses/LICENSE-EXPLAINED.txt,sha256=WFREvTpfTjPjDHpOLADxJpCKpIla3Ht87RUUGii4ODU,606
-boto3_assist-0.20.0.dist-info/licenses/LICENSE.txt,sha256=PXDhFWS5L5aOTkVhNvoitHKbAkgxqMI2uUPQyrnXGiI,1105
-boto3_assist-0.20.0.dist-info/RECORD,,
+boto3_assist-0.22.0.dist-info/METADATA,sha256=fvChz9xIsO1PiE8HD8zzg4m1FMytpFhDJJMJcM6BKWw,2875
+boto3_assist-0.22.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+boto3_assist-0.22.0.dist-info/licenses/LICENSE-EXPLAINED.txt,sha256=WFREvTpfTjPjDHpOLADxJpCKpIla3Ht87RUUGii4ODU,606
+boto3_assist-0.22.0.dist-info/licenses/LICENSE.txt,sha256=PXDhFWS5L5aOTkVhNvoitHKbAkgxqMI2uUPQyrnXGiI,1105
+boto3_assist-0.22.0.dist-info/RECORD,,