docs: new parser utility

aws_lambda_powertools/utilities/parser/__init__.py

@@ -2,16 +2,17 @@
 """
 from . import envelopes
 from .envelopes import BaseEnvelope
-from .exceptions import ModelValidationError
-from .parser import event_parser
-from .pydantic import BaseModel, root_validator, validator
+from .parser import event_parser, parse
+from .pydantic import BaseModel, Field, ValidationError, root_validator, validator
 
 __all__ = [
     "event_parser",
+    "parse",
     "envelopes",
     "BaseEnvelope",
     "BaseModel",
+    "Field",
     "validator",
     "root_validator",
-    "ModelValidationError",
+    "ValidationError",
 ]

aws_lambda_powertools/utilities/parser/envelopes/__init__.py

@@ -1,6 +1,6 @@
 from .base import BaseEnvelope
-from .dynamodb import DynamoDBEnvelope
+from .dynamodb import DynamoDBStreamEnvelope
 from .event_bridge import EventBridgeEnvelope
 from .sqs import SqsEnvelope
 
-__all__ = ["DynamoDBEnvelope", "EventBridgeEnvelope", "SqsEnvelope", "BaseEnvelope"]
+__all__ = ["DynamoDBStreamEnvelope", "EventBridgeEnvelope", "SqsEnvelope", "BaseEnvelope"]

aws_lambda_powertools/utilities/parser/envelopes/dynamodb.py

@@ -10,7 +10,7 @@
 logger = logging.getLogger(__name__)
 
 
-class DynamoDBEnvelope(BaseEnvelope):
+class DynamoDBStreamEnvelope(BaseEnvelope):
     """ DynamoDB Stream Envelope to extract data within NewImage/OldImage
 
     Note: Values are the parsed models. Images' values can also be None, and
@@ -32,8 +32,10 @@ def parse(self, data: Dict[str, Any], model: BaseModel) -> List[Dict[Literal["Ne
         List
             List of records parsed with model provided
         """
+        logger.debug(f"Parsing incoming data with DynamoDB Stream model {DynamoDBStreamModel}")
         parsed_envelope = DynamoDBStreamModel(**data)
         output = []
+        logger.debug(f"Parsing DynamoDB Stream new and old records with {model}")
         for record in parsed_envelope.Records:
             output.append(
                 {

aws_lambda_powertools/utilities/parser/envelopes/event_bridge.py

@@ -27,5 +27,7 @@ def parse(self, data: Dict[str, Any], model: BaseModel) -> BaseModel:
         Any
             Parsed detail payload with model provided
         """
+        logger.debug(f"Parsing incoming data with EventBridge model {EventBridgeModel}")
         parsed_envelope = EventBridgeModel(**data)
+        logger.debug(f"Parsing event payload in `detail` with {model}")
         return self._parse(data=parsed_envelope.detail, model=model)

aws_lambda_powertools/utilities/parser/envelopes/sqs.py

@@ -19,7 +19,7 @@ class SqsEnvelope(BaseEnvelope):
     all items in the list will be parsed as str and npt as JSON (and vice versa)
     """
 
-    def parse(self, data: Dict[str, Any], model: Union[BaseModel, str]) -> List[Union[BaseModel, str]]:
+    def parse(self, data: Dict[str, Any], model: Union[BaseModel, str]) -> List[BaseModel]:
         """Parses records found with model provided
 
         Parameters
@@ -34,8 +34,10 @@ def parse(self, data: Dict[str, Any], model: Union[BaseModel, str]) -> List[Unio
         List
             List of records parsed with model provided
         """
+        logger.debug(f"Parsing incoming data with SQS model {SqsModel}")
         parsed_envelope = SqsModel(**data)
         output = []
+        logger.debug(f"Parsing SQS records in `body` with {model}")
         for record in parsed_envelope.Records:
             output.append(self._parse(record.body, model))
         return output

aws_lambda_powertools/utilities/parser/exceptions.py

@@ -2,9 +2,5 @@ class InvalidEnvelopeError(Exception):
     """Input envelope is not callable and instance of BaseEnvelope"""
 
 
-class ModelValidationError(Exception):
-    """Input data does not conform with model"""
-
-
 class InvalidModelTypeError(Exception):
     """Input data model does not implement BaseModel"""

aws_lambda_powertools/utilities/parser/parser.py

@@ -1,13 +1,15 @@
 import logging
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Callable, Dict, Optional, Type, TypeVar
 
-from pydantic import BaseModel, ValidationError
+from pydantic import BaseModel
 
 from ...middleware_factory import lambda_handler_decorator
 from ..typing import LambdaContext
 from .envelopes.base import BaseEnvelope
-from .exceptions import InvalidEnvelopeError, InvalidModelTypeError, ModelValidationError
+from .exceptions import InvalidEnvelopeError, InvalidModelTypeError
 
+Model = TypeVar("Model", bound=BaseModel)
+Envelope = TypeVar("Envelope", bound=BaseEnvelope)
 logger = logging.getLogger(__name__)
 
 
@@ -16,8 +18,8 @@ def event_parser(
     handler: Callable[[Dict, Any], Any],
     event: Dict[str, Any],
     context: LambdaContext,
-    model: BaseModel,
-    envelope: Optional[BaseEnvelope] = None,
+    model: Type[Model],
+    envelope: Optional[Type[Envelope]] = None,
 ) -> Any:
     """Lambda handler decorator to parse & validate events using Pydantic models
 
@@ -72,7 +74,7 @@ def handler(event: Order, context: LambdaContext):
 
     Raises
     ------
-    ModelValidationError
+    ValidationError
         When input event does not conform with model provided
     InvalidModelTypeError
         When model given does not implement BaseModel
@@ -84,7 +86,7 @@ def handler(event: Order, context: LambdaContext):
     return handler(parsed_event, context)
 
 
-def parse(event: Dict[str, Any], model: BaseModel, envelope: Optional[BaseEnvelope] = None) -> Any:
+def parse(event: Dict[str, Any], model: Type[Model], envelope: Optional[Type[Envelope]] = None) -> Any:
     """Standalone function to parse & validate events using Pydantic models
 
     Typically used when you need fine-grained control over error handling compared to event_parser decorator.
@@ -94,7 +96,7 @@ def parse(event: Dict[str, Any], model: BaseModel, envelope: Optional[BaseEnvelo
 
     **Lambda handler decorator to parse & validate event**
 
-        from aws_lambda_powertools.utilities.parser.exceptions import ModelValidationError
+        from aws_lambda_powertools.utilities.parser import ValidationError
 
         class Order(BaseModel):
             id: int
@@ -104,7 +106,7 @@ class Order(BaseModel):
         def handler(event: Order, context: LambdaContext):
             try:
                 parse(model=Order)
-            except ModelValidationError:
+            except ValidationError:
                 ...
 
     **Lambda handler decorator to parse & validate event - using built-in envelope**
@@ -117,7 +119,7 @@ class Order(BaseModel):
         def handler(event: Order, context: LambdaContext):
             try:
                 parse(model=Order, envelope=envelopes.EVENTBRIDGE)
-            except ModelValidationError:
+            except ValidationError:
                 ...
 
     Parameters
@@ -131,7 +133,7 @@ def handler(event: Order, context: LambdaContext):
 
     Raises
     ------
-    ModelValidationError
+    ValidationError
         When input event does not conform with model provided
     InvalidModelTypeError
         When model given does not implement BaseModel
@@ -144,13 +146,12 @@ def handler(event: Order, context: LambdaContext):
             return envelope().parse(data=event, model=model)
         except AttributeError:
             raise InvalidEnvelopeError(f"Envelope must implement BaseEnvelope, envelope={envelope}")
-        except (ValidationError, TypeError) as e:
-            raise ModelValidationError(f"Input event does not conform with model, envelope={envelope}") from e
 
     try:
         logger.debug("Parsing and validating event model; no envelope used")
+        if isinstance(event, str):
+            return model.parse_raw(event)
+
         return model.parse_obj(event)
-    except (ValidationError, TypeError) as e:
-        raise ModelValidationError("Input event does not conform with model") from e
     except AttributeError:
-        raise InvalidModelTypeError("Input model must implement BaseModel")
+        raise InvalidModelTypeError(f"Input model must implement BaseModel, model={model}")