improv: envelope structure & import

Author: heitorlessa

aws_lambda_powertools/utilities/parser/__init__.py

@@ -1,6 +1,6 @@
 """Advanced parser utility
 """
-from .envelopes import Envelope, InvalidEnvelopeError, parse_envelope
+from . import envelopes
 from .parser import parser
 
-__all__ = ["InvalidEnvelopeError", "Envelope", "parse_envelope", "parser"]
+__all__ = ["envelopes", "parser"]

aws_lambda_powertools/utilities/parser/envelopes/__init__.py

@@ -1,3 +1,7 @@
-from .envelopes import Envelope, InvalidEnvelopeError, parse_envelope
+from .dynamodb import DynamoDBEnvelope
+from .event_bridge import EventBridgeEnvelope
+from .sqs import SqsEnvelope
 
-__all__ = ["InvalidEnvelopeError", "Envelope", "parse_envelope"]
+SQS = SqsEnvelope
+DYNAMODB_STREAM = DynamoDBEnvelope
+EVENTBRIDGE = EventBridgeEnvelope

aws_lambda_powertools/utilities/parser/envelopes/base.py

@@ -4,6 +4,8 @@
 
 from pydantic import BaseModel, ValidationError
 
+from ..exceptions import InvalidEnvelopeError
+
 logger = logging.getLogger(__name__)
 
 
@@ -38,3 +40,11 @@ def _parse_user_json_string_schema(user_event: str, schema: BaseModel) -> Any:
     @abstractmethod
     def parse(self, event: Dict[str, Any], schema: BaseModel):
         return NotImplemented
+
+
+def parse_envelope(event: Dict[str, Any], envelope: BaseEnvelope, schema: BaseModel):
+    if not callable(envelope) and not isinstance(BaseEnvelope):
+        logger.exception("envelope must be a callable and instance of BaseEnvelope")
+        raise InvalidEnvelopeError("envelope must be a callable and instance of BaseEnvelope")
+    logger.debug(f"Parsing and validating event schema, envelope={envelope}")
+    return envelope().parse(event=event, schema=schema)

aws_lambda_powertools/utilities/parser/envelopes/dynamodb.py

@@ -4,17 +4,34 @@
 from pydantic import BaseModel, ValidationError
 from typing_extensions import Literal
 
-from aws_lambda_powertools.utilities.parser.envelopes.base import BaseEnvelope
-from aws_lambda_powertools.utilities.parser.schemas import DynamoDBSchema
+from ..schemas import DynamoDBSchema
+from .base import BaseEnvelope
 
 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):
+    """ DynamoDB Stream Envelope to extract data within NewImage/OldImage
+
+    Note: Values are the parsed schema models. Images' values can also be None, and
+    length of the list is the record's amount in the original event.
+    """
+
     def parse(self, event: Dict[str, Any], schema: BaseModel) -> List[Dict[Literal["NewImage", "OldImage"], BaseModel]]:
+        """Parses DynamoDB Stream records found in either NewImage and OldImage with schema provided
+
+        Parameters
+        ----------
+        event : Dict
+            Lambda event to be parsed
+        schema : BaseModel
+            User schema provided to parse after extracting data using envelope
+
+        Returns
+        -------
+        List
+            List of records parsed with schema provided
+        """
         try:
             parsed_envelope = DynamoDBSchema(**event)
         except (ValidationError, TypeError):

aws_lambda_powertools/utilities/parser/envelopes/envelopes.py

@@ -9,9 +9,24 @@
 logger = logging.getLogger(__name__)
 
 
-# returns a parsed BaseModel object according to schema type
 class EventBridgeEnvelope(BaseEnvelope):
+    """EventBridge envelope to extract data in detail key"""
+
     def parse(self, event: Dict[str, Any], schema: BaseModel) -> BaseModel:
+        """Parses data found with schema provided
+
+        Parameters
+        ----------
+        event : Dict
+            Lambda event to be parsed
+        schema : BaseModel
+            User schema provided to parse after extracting data using envelope
+
+        Returns
+        -------
+        Any
+            Parsed detail payload with schema provided
+        """
         try:
             parsed_envelope = EventBridgeSchema(**event)
         except (ValidationError, TypeError):

aws_lambda_powertools/utilities/parser/envelopes/event_bridge.py

@@ -3,19 +3,37 @@
 
 from pydantic import BaseModel, ValidationError
 
-from aws_lambda_powertools.utilities.parser.envelopes.base import BaseEnvelope
-from aws_lambda_powertools.utilities.parser.schemas import SqsSchema
+from ..schemas import SqsSchema
+from .base import BaseEnvelope
 
 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):
+    """SQS Envelope to extract array of Records
+
+    The record's body parameter is a string, though it can also be a JSON encoded string.
+    Regardless of it's type it'll be parsed into a BaseModel object.
+
+    Note: Records will be parsed the same way so if schema is str,
+    all items in the list will be parsed as str and npt as JSON (and vice versa)
+    """
+
     def parse(self, event: Dict[str, Any], schema: Union[BaseModel, str]) -> List[Union[BaseModel, str]]:
+        """Parses records found with schema provided
+
+        Parameters
+        ----------
+        event : Dict
+            Lambda event to be parsed
+        schema : BaseModel
+            User schema provided to parse after extracting data using envelope
+
+        Returns
+        -------
+        List
+            List of records parsed with schema provided
+        """
         try:
             parsed_envelope = SqsSchema(**event)
         except (ValidationError, TypeError):

aws_lambda_powertools/utilities/parser/envelopes/sqs.py

@@ -0,0 +1,2 @@
+class InvalidEnvelopeError(Exception):
+    """Input envelope is not one of the Envelope enum values"""

aws_lambda_powertools/utilities/parser/exceptions.py

@@ -4,7 +4,8 @@
 from pydantic import BaseModel, ValidationError
 
 from aws_lambda_powertools.middleware_factory import lambda_handler_decorator
-from aws_lambda_powertools.utilities.parser.envelopes import Envelope, parse_envelope
+
+from .envelopes.base import BaseEnvelope, parse_envelope
 
 logger = logging.getLogger(__name__)
 
@@ -15,7 +16,7 @@ def parser(
     event: Dict[str, Any],
     context: Dict[str, Any],
     schema: BaseModel,
-    envelope: Optional[Envelope] = None,
+    envelope: Optional[BaseEnvelope] = None,
 ) -> Any:
     """Decorator to conduct advanced parsing & validation for lambda handlers events
 

aws_lambda_powertools/utilities/parser/parser.py

@@ -3,14 +3,14 @@
 import pytest
 from pydantic.error_wrappers import ValidationError
 
-from aws_lambda_powertools.utilities.parser.envelopes.envelopes import Envelope
+from aws_lambda_powertools.utilities.parser import envelopes
 from aws_lambda_powertools.utilities.parser.parser import parser
 from aws_lambda_powertools.utilities.typing import LambdaContext
 from tests.functional.parser.schemas import MyAdvancedDynamoBusiness, MyDynamoBusiness
 from tests.functional.parser.utils import load_event
 
 
-@parser(schema=MyDynamoBusiness, envelope=Envelope.DYNAMODB_STREAM)
+@parser(schema=MyDynamoBusiness, envelope=envelopes.DYNAMODB_STREAM)
 def handle_dynamodb(event: List[Dict[str, MyDynamoBusiness]], _: LambdaContext):
     assert len(event) == 2
     assert event[0]["OldImage"] is None