improv: add docstrings; event internal param renamed

Author: heitorlessa

aws_lambda_powertools/utilities/parser/envelopes/base.py

@@ -11,18 +11,48 @@ class BaseEnvelope(ABC):
     """ABC implementation for creating a supported Envelope"""
 
     @staticmethod
-    def _parse(event: Union[Dict[str, Any], str], schema: BaseModel) -> Any:
-        if event is None:
+    def _parse(data: Union[Dict[str, Any], str], schema: BaseModel) -> Any:
+        """Parses envelope data against schema provided
+
+        Parameters
+        ----------
+        data : Dict
+            Data to be parsed and validated
+        schema
+            Schema to parse and validate data against
+
+        Returns
+        -------
+        Any
+            Parsed data
+        """
+        if data is None:
             logger.debug("Skipping parsing as event is None")
-            return event
+            return data
 
         logger.debug("parsing event against schema")
-        if isinstance(event, str):
+        if isinstance(data, str):
             logger.debug("parsing event as string")
-            return schema.parse_raw(event)
+            return schema.parse_raw(data)
 
-        return schema.parse_obj(event)
+        return schema.parse_obj(data)
 
     @abstractmethod
-    def parse(self, event: Dict[str, Any], schema: BaseModel):
+    def parse(self, data: Dict[str, Any], schema: BaseModel):
+        """Implementation to parse data against envelope schema, then against the schema
+
+        NOTE: Call `_parse` method to fully parse data with schema provided.
+
+        Example
+        -------
+
+        **EventBridge envelope implementation example**
+
+        def parse(...):
+            # 1. parses data against envelope schema
+            parsed_envelope = EventBridgeSchema(**data)
+
+            # 2. parses portion of data within the envelope against schema
+            return self._parse(data=parsed_envelope.detail, schema=schema)
+        """
         return NotImplemented  # pragma: no cover

aws_lambda_powertools/utilities/parser/envelopes/dynamodb.py

@@ -17,12 +17,12 @@ class DynamoDBEnvelope(BaseEnvelope):
     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]]:
+    def parse(self, data: 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
+        data : Dict
             Lambda event to be parsed
         schema : BaseModel
             User schema provided to parse after extracting data using envelope
@@ -32,7 +32,7 @@ def parse(self, event: Dict[str, Any], schema: BaseModel) -> List[Dict[Literal["
         List
             List of records parsed with schema provided
         """
-        parsed_envelope = DynamoDBSchema(**event)
+        parsed_envelope = DynamoDBSchema(**data)
         output = []
         for record in parsed_envelope.Records:
             output.append(

aws_lambda_powertools/utilities/parser/envelopes/event_bridge.py

@@ -10,14 +10,14 @@
 
 
 class EventBridgeEnvelope(BaseEnvelope):
-    """EventBridge envelope to extract data in detail key"""
+    """EventBridge envelope to extract data within detail key"""
 
-    def parse(self, event: Dict[str, Any], schema: BaseModel) -> BaseModel:
+    def parse(self, data: Dict[str, Any], schema: BaseModel) -> BaseModel:
         """Parses data found with schema provided
 
         Parameters
         ----------
-        event : Dict
+        data : Dict
             Lambda event to be parsed
         schema : BaseModel
             User schema provided to parse after extracting data using envelope
@@ -27,5 +27,5 @@ def parse(self, event: Dict[str, Any], schema: BaseModel) -> BaseModel:
         Any
             Parsed detail payload with schema provided
         """
-        parsed_envelope = EventBridgeSchema(**event)
-        return self._parse(parsed_envelope.detail, schema)
+        parsed_envelope = EventBridgeSchema(**data)
+        return self._parse(data=parsed_envelope.detail, schema=schema)

aws_lambda_powertools/utilities/parser/envelopes/sqs.py

@@ -19,12 +19,12 @@ class SqsEnvelope(BaseEnvelope):
     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]]:
+    def parse(self, data: Dict[str, Any], schema: Union[BaseModel, str]) -> List[Union[BaseModel, str]]:
         """Parses records found with schema provided
 
         Parameters
         ----------
-        event : Dict
+        data : Dict
             Lambda event to be parsed
         schema : BaseModel
             User schema provided to parse after extracting data using envelope
@@ -34,7 +34,7 @@ def parse(self, event: Dict[str, Any], schema: Union[BaseModel, str]) -> List[Un
         List
             List of records parsed with schema provided
         """
-        parsed_envelope = SqsSchema(**event)
+        parsed_envelope = SqsSchema(**data)
         output = []
         for record in parsed_envelope.Records:
             output.append(self._parse(record.body, schema))

aws_lambda_powertools/utilities/parser/parser.py

@@ -5,6 +5,7 @@
 
 from aws_lambda_powertools.middleware_factory import lambda_handler_decorator
 
+from ..typing import LambdaContext
 from .envelopes.base import BaseEnvelope
 from .exceptions import InvalidEnvelopeError, InvalidSchemaTypeError, SchemaValidationError
 
@@ -15,79 +16,119 @@
 def parser(
     handler: Callable[[Dict, Any], Any],
     event: Dict[str, Any],
-    context: Dict[str, Any],
+    context: LambdaContext,
     schema: BaseModel,
     envelope: Optional[BaseEnvelope] = None,
 ) -> Any:
-    """Decorator to conduct advanced parsing & validation for lambda handlers events
+    """Lambda handler decorator to parse & validate events using Pydantic models
 
-    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 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.
+    It requires a schema that implements Pydantic BaseModel to parse & validate the event.
+
+    When an envelope is given, it'll use the following logic:
+
+    1. Parse the event against envelope schema first e.g. EnvelopeSchema(**event)
+    2. Envelope will extract a given key to be parsed against the schema e.g. event.detail
+
+    This is useful when you need to confirm event wrapper structure, and
+    b) selectively extract a portion of your payload for parsing & validation.
+
+    NOTE: If envelope is omitted, the complete event is parsed to match the schema parameter BaseModel definition.
 
     Example
     -------
-    **Lambda function using validation decorator**
+    **Lambda handler decorator to parse & validate event**
+
+        class Order(BaseModel):
+            id: int
+            description: str
+            ...
+
+        @parser(schema=Order)
+        def handler(event: Order, context: LambdaContext):
+            ...
+
+    **Lambda handler decorator to parse & validate event - using built-in envelope**
+
+        class Order(BaseModel):
+            id: int
+            description: str
+            ...
 
-        @parser(schema=MyBusiness, envelope=envelopes.EVENTBRIDGE)
-        def handler(event: MyBusiness , context: LambdaContext):
+        @parser(schema=Order, envelope=envelopes.EVENTBRIDGE)
+        def handler(event: Order, context: LambdaContext):
             ...
 
     Parameters
     ----------
-    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.
+    handler:  Callable
+        Method to annotate on
+    event:    Dict
+        Lambda event to be parsed & validated
+    context:  LambdaContext
+        Lambda context object
+    schema:   BaseModel
+        Your data schema that will replace the event.
+    envelope: BaseEnvelope
+        Optional envelope to extract the schema from
 
     Raises
     ------
     SchemaValidationError
         When input event does not conform with schema provided
     InvalidSchemaTypeError
         When schema given does not implement BaseModel
+    InvalidEnvelopeError
+        When envelope given does not implement BaseEnvelope
     """
     parsed_event = parse(event=event, schema=schema, envelope=envelope)
     logger.debug(f"Calling handler {handler.__name__}")
     return handler(parsed_event, context)
 
 
 def parse(event: Dict[str, Any], schema: BaseModel, envelope: Optional[BaseEnvelope] = None) -> Any:
-    """
-    Standalone parse function to conduct advanced parsing & validation for lambda handlers events
+    """Standalone function to parse & validate events using Pydantic models
 
-    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 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.
+    Typically used when you need fine-grained control over error handling compared to parser decorator.
 
     Example
     -------
-    **Lambda function using standalone parse**
 
-        def handler(event: MyBusiness , context: LambdaContext):
-            parse(event=event, schema=MyBusiness, envelope=envelopes.EVENTBRIDGE)
+    **Lambda handler decorator to parse & validate event**
+
+        from aws_lambda_powertools.utilities.parser.exceptions import SchemaValidationError
+
+        class Order(BaseModel):
+            id: int
+            description: str
             ...
 
+        def handler(event: Order, context: LambdaContext):
+            try:
+                parse(schema=Order)
+            except SchemaValidationError:
+                ...
+
+    **Lambda handler decorator to parse & validate event - using built-in envelope**
+
+        class Order(BaseModel):
+            id: int
+            description: str
+            ...
+
+        def handler(event: Order, context: LambdaContext):
+            try:
+                parse(schema=Order, envelope=envelopes.EVENTBRIDGE)
+            except SchemaValidationError:
+                ...
+
     Parameters
     ----------
-    event:    AWS event dictionary
-    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.
+    event:    Dict
+        Lambda event to be parsed & validated
+    schema:   BaseModel
+        Your data schema that will replace the event.
+    envelope: BaseEnvelope
+        Optional envelope to extract the schema from
 
     Raises
     ------
@@ -101,7 +142,7 @@ def handler(event: MyBusiness , context: LambdaContext):
     if envelope and callable(envelope):
         try:
             logger.debug(f"Parsing and validating event schema with envelope={envelope}")
-            return envelope().parse(event=event, schema=schema)
+            return envelope().parse(data=event, schema=schema)
         except AttributeError:
             raise InvalidEnvelopeError(f"Envelope must implement BaseEnvelope, envelope={envelope}")
         except (ValidationError, TypeError) as e:

tests/functional/parser/conftest.py

@@ -37,11 +37,11 @@ def dummy_envelope(dummy_envelope_schema):
     class MyDummyEnvelope(BaseEnvelope):
         """Unwrap dummy event within payload key"""
 
-        def parse(self, event: Dict[str, Any], schema: BaseModel):
+        def parse(self, data: Dict[str, Any], schema: BaseModel):
             try:
-                parsed_enveloped = dummy_envelope_schema(**event)
+                parsed_enveloped = dummy_envelope_schema(**data)
             except (ValidationError, TypeError) as e:
                 raise SchemaValidationError("Dummy input does not conform with schema") from e
-            return self._parse(event=parsed_enveloped.payload, schema=schema)
+            return self._parse(data=parsed_enveloped.payload, schema=schema)
 
     return MyDummyEnvelope