fix: CR fixes

Merge branch 'develop' of https://github.com/awslabs/aws-lambda-powertools-python into pydantic

Author: Ran Isenberg

Makefile

@@ -4,7 +4,6 @@ target:
 
 dev:
 	pip install --upgrade pip poetry pre-commit
-	poetry install
 	poetry install --extras "pydantic"
 	pre-commit install
 

aws_lambda_powertools/utilities/advanced_parser/envelopes/base.py

@@ -21,7 +21,8 @@ def _parse_user_dict_schema(self, user_event: Dict[str, Any], schema: BaseModel)
     def _parse_user_json_string_schema(self, user_event: str, schema: BaseModel) -> Any:
         if user_event is None:
             return None
-        logger.debug("parsing user dictionary schema")
+        # this is used in cases where the underlying schema is not a Dict that can be parsed as baseModel
+        # but a plain string i.e SQS has plain string payload
         if schema == str:
             logger.debug("input is string, returning")
             return user_event

aws_lambda_powertools/utilities/advanced_parser/envelopes/dynamodb.py

@@ -1,5 +1,6 @@
 import logging
-from typing import Any, Dict
+from typing import Any, Dict, List
+from typing_extensions import Literal
 
 from pydantic import BaseModel, ValidationError
 
@@ -9,8 +10,11 @@
 logger = logging.getLogger(__name__)
 
 
+# returns a List of dictionaries which each contains two keys, "NewImage" and "OldImage".
+# The values are the parsed schema models. The images' values can also be None.
+# Length of the list is the record's amount in the original event.
 class DynamoDBEnvelope(BaseEnvelope):
-    def parse(self, event: Dict[str, Any], schema: BaseModel) -> Any:
+    def parse(self, event: Dict[str, Any], schema: BaseModel) -> List[Dict[Literal["NewImage", "OldImage"], BaseModel]]:
         try:
             parsed_envelope = DynamoDBSchema(**event)
         except (ValidationError, TypeError):

aws_lambda_powertools/utilities/advanced_parser/envelopes/event_bridge.py

@@ -9,8 +9,9 @@
 logger = logging.getLogger(__name__)
 
 
+# returns a parsed BaseModel object according to schema type
 class EventBridgeEnvelope(BaseEnvelope):
-    def parse(self, event: Dict[str, Any], schema: BaseModel) -> Any:
+    def parse(self, event: Dict[str, Any], schema: BaseModel) -> BaseModel:
         try:
             parsed_envelope = EventBridgeSchema(**event)
         except (ValidationError, TypeError):

aws_lambda_powertools/utilities/advanced_parser/envelopes/sqs.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Union
 
 from pydantic import BaseModel, ValidationError
 
@@ -9,8 +9,13 @@
 logger = logging.getLogger(__name__)
 
 
+# returns a list of parsed schemas of type BaseModel or plain string.
+# The record's body parameter is a string. However, it can also be a JSON encoded string which
+# can then be parsed into a BaseModel object.
+# Note that all records will be parsed the same way so if schema is str,
+# all the items in the list will be parsed as str and npt as JSON (and vice versa).
 class SqsEnvelope(BaseEnvelope):
-    def parse(self, event: Dict[str, Any], schema: BaseModel) -> List[BaseModel]:
+    def parse(self, event: Dict[str, Any], schema: Union[BaseModel, str]) -> List[Union[BaseModel, str]]:
         try:
             parsed_envelope = SqsSchema(**event)
         except (ValidationError, TypeError):

aws_lambda_powertools/utilities/advanced_parser/parser.py

@@ -21,24 +21,36 @@ def parser(
 
         As Lambda follows (event, context) signature we can remove some of the boilerplate
         and also capture any exception any Lambda function throws as metadata.
-        Event will be the parsed & validated BaseModel pydantic object of the input type "schema"
+        event will be the parsed and passed as a BaseModel pydantic class of the input type "schema" 
+        to the lambda handler.
+        event will be extracted from the envelope in case envelope is not None.
+        In case envelope is None, the complete event is parsed to match the schema parameter BaseModel definition.
+        In case envelope is not None, first the event is parsed as the envelope's schema definition, and the user 
+        message is extracted and parsed again as the schema parameter's definition.
 
         Example
         -------
         **Lambda function using validation decorator**
 
             @parser(schema=MyBusiness, envelope=envelopes.EVENTBRIDGE)
-            def handler(event: inbound_schema_model , context: LambdaContext):
+            def handler(event: MyBusiness , context: LambdaContext):
                 ...
 
         Parameters
         ----------
-        todo add
+        handler:  input for lambda_handler_decorator, wraps the handler lambda
+        event:    AWS event dictionary
+        context:  AWS lambda context
+        schema:   pydantic BaseModel class. This is the user data schema that will replace the event. 
+                  event parameter will be parsed and a new schema object will be created from it.
+        envelope: what envelope to extract the schema from, can be any AWS service that is currently 
+                  supported in the envelopes module. Can be None.
 
         Raises
         ------
         err
-            TypeError or pydantic.ValidationError or any exception raised by the lambda handler itself
+            TypeError - in case event is None
+            pydantic.ValidationError - event fails validation, either of the envelope
     """
     lambda_handler_name = handler.__name__
     parsed_event = None
@@ -53,4 +65,4 @@ def handler(event: inbound_schema_model , context: LambdaContext):
         parsed_event = parse_envelope(event, envelope, schema)
 
     logger.debug(f"Calling handler {lambda_handler_name}")
-    handler(parsed_event, context)
+    return handler(parsed_event, context)

aws_lambda_powertools/utilities/advanced_parser/schemas/dynamodb.py

@@ -14,6 +14,8 @@ class DynamoScheme(BaseModel):
     SizeBytes: int
     StreamViewType: Literal["NEW_AND_OLD_IMAGES", "KEYS_ONLY", "NEW_IMAGE", "OLD_IMAGE"]
 
+    # since both images are optional, they can both be None. However, at least one must
+    # exist in a legal schema of NEW_AND_OLD_IMAGES type
     @root_validator
     def check_one_image_exists(cls, values):
         newimg, oldimg = values.get("NewImage"), values.get("OldImage")

aws_lambda_powertools/utilities/advanced_parser/schemas/sqs.py

@@ -24,13 +24,17 @@ class SqsMsgAttributeSchema(BaseModel):
     binaryListValues: List[str] = []
     dataType: str
 
+    # Amazon SQS supports the logical data types String, Number, and Binary with optional custom data type
+    # labels with the format .custom-data-type.
+    # https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-metadata.html#sqs-message-attributes
     @validator("dataType")
     def valid_type(cls, v):  # noqa: VNE001
         pattern = re.compile("Number.*|String.*|Binary.*")
         if not pattern.match(v):
             raise TypeError("data type is invalid")
         return v
 
+    # validate that dataType and value are not None and match 
     @root_validator
     def check_str_and_binary_values(cls, values):
         binary_val, str_val = values.get("binaryValue", ""), values.get("stringValue", "")