docs(parser): change parser documentation (#5262)

* changed parser documentation

* changed parser documentation

* changed parser documentation

* changed parser documentation

* change the code from the doc to examples folder

* add line highlights and fix sub header typo

* fix typos, pydantic install, and add built in envelope example

* changed the example from built in env to models

* fix validationerror import

* Changing highlights + import

* Changing highlights + import

* Changing highlights + import

* Addressing Andrea's feedback

---------

Signed-off-by: Ana Falcão <[email protected]>
Co-authored-by: Falcao <[email protected]>
Co-authored-by: Leandro Damascena <[email protected]>

Author: 3 people

.github/workflows/quality_check.yml

@@ -20,6 +20,7 @@ on:
     paths:
       - "aws_lambda_powertools/**"
       - "tests/**"
+      - "examples/**"
       - "pyproject.toml"
       - "poetry.lock"
       - "mypy.ini"
@@ -30,6 +31,7 @@ on:
     paths:
       - "aws_lambda_powertools/**"
       - "tests/**"
+      - "examples/**"
       - "pyproject.toml"
       - "poetry.lock"
       - "mypy.ini"

docs/utilities/parser.md

@@ -0,0 +1,15 @@
+{
+    "version": "0",
+    "id": "12345678-1234-1234-1234-123456789012",
+    "detail-type": "Order Placed",
+    "source": "com.mycompany.orders",
+    "account": "123456789012",
+    "time": "2023-05-03T12:00:00Z",
+    "region": "us-west-2",
+    "resources": [],
+    "detail": {
+        "order_id": "ORD-12345",
+        "amount": 99.99,
+        "customer_id": "CUST-6789"
+    }
+}

examples/parser/src/bring_your_own_envelope.json

@@ -0,0 +1,51 @@
+import json
+from typing import Any, Dict, Optional, Type, TypeVar, Union
+
+from pydantic import BaseModel
+
+from aws_lambda_powertools.utilities.parser import BaseEnvelope, event_parser
+from aws_lambda_powertools.utilities.parser.models import EventBridgeModel
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+Model = TypeVar("Model", bound=BaseModel)
+
+
+class EventBridgeEnvelope(BaseEnvelope):
+    def parse(self, data: Optional[Union[Dict[str, Any], Any]], model: Type[Model]) -> Optional[Model]:
+        if data is None:
+            return None
+
+        parsed_envelope = EventBridgeModel.model_validate(data)
+        return self._parse(data=parsed_envelope.detail, model=model)
+
+
+class OrderDetail(BaseModel):
+    order_id: str
+    amount: float
+    customer_id: str
+
+
+@event_parser(model=OrderDetail, envelope=EventBridgeEnvelope)
+def lambda_handler(event: OrderDetail, context: LambdaContext):
+    try:
+        # Process the order
+        print(f"Processing order {event.order_id} for customer {event.customer_id}")
+        print(f"Order amount: ${event.amount:.2f}")
+
+        # Your business logic here
+        # For example, you might save the order to a database or trigger a payment process
+
+        return {
+            "statusCode": 200,
+            "body": json.dumps(
+                {
+                    "message": f"Order {event.order_id} processed successfully",
+                    "order_id": event.order_id,
+                    "amount": event.amount,
+                    "customer_id": event.customer_id,
+                },
+            ),
+        }
+    except Exception as e:
+        print(f"Error processing order: {str(e)}")
+        return {"statusCode": 500, "body": json.dumps({"error": "Internal server error"})}

examples/parser/src/bring_your_own_envelope.py

@@ -0,0 +1,21 @@
+from pydantic import Field, ValidationError
+
+from aws_lambda_powertools.utilities.parser import parse
+from aws_lambda_powertools.utilities.parser.models import EventBridgeModel
+
+
+# Define a custom EventBridge model by extending the built-in EventBridgeModel
+class MyCustomEventBridgeModel(EventBridgeModel):
+    detail_type: str = Field(alias="detail-type")
+    source: str
+    detail: dict
+
+
+def lambda_handler(event: dict, context):
+    try:
+        # Manually parse the incoming event into the custom model
+        parsed_event: MyCustomEventBridgeModel = parse(model=MyCustomEventBridgeModel, event=event)
+
+        return {"statusCode": 200, "body": f"Event from {parsed_event.source}, type: {parsed_event.detail_type}"}
+    except ValidationError as e:
+        return {"statusCode": 400, "body": f"Validation error: {str(e)}"}

examples/parser/src/custom_data_model_with_eventbridge.py

@@ -0,0 +1,14 @@
+{
+    "version": "0",
+    "id": "abcd-1234-efgh-5678",
+    "detail-type": "order.created",
+    "source": "my.order.service",
+    "account": "123456789012",
+    "time": "2023-09-10T12:00:00Z",
+    "region": "us-west-2",
+    "resources": [],
+    "detail": {
+        "orderId": "O-12345",
+        "amount": 100.0
+    }
+}

examples/parser/src/data_model_eventbridge.json

@@ -0,0 +1,17 @@
+{
+    "version": "0",
+    "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
+    "detail-type": "CustomerSignedUp",
+    "source": "CustomerService",
+    "account": "111122223333",
+    "time": "2020-10-22T18:43:48Z",
+    "region": "us-west-1",
+    "resources": [
+        "some_additional_"
+    ],
+    "detail": {
+        "username": "universe",
+        "parentid_1": "12345",
+        "parentid_2": "6789"
+    }
+}

examples/parser/src/envelope_payload.json

@@ -0,0 +1,20 @@
+from pydantic import BaseModel
+
+from aws_lambda_powertools.utilities.parser import envelopes, event_parser
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+class UserModel(BaseModel):
+    username: str
+    parentid_1: str
+    parentid_2: str
+
+
+@event_parser(model=UserModel, envelope=envelopes.EventBridgeEnvelope)
+def lambda_handler(event: UserModel, context: LambdaContext):
+    if event.parentid_1 != event.parentid_2:
+        return {"statusCode": 400, "body": "Parent ids do not match"}
+
+    # If parentids match, proceed with user registration
+
+    return {"statusCode": 200, "body": f"User {event.username} registered successfully"}

examples/parser/src/envelope_with_event_parser.py

@@ -0,0 +1,4 @@
+{
+    "id": "12345",
+    "name": "Jane Doe"
+}

examples/parser/src/example_event_parser.json

@@ -0,0 +1,22 @@
+from pydantic import BaseModel, field_validator
+
+from aws_lambda_powertools.utilities.parser import parse
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+class HelloWorldModel(BaseModel):
+    message: str
+
+    @field_validator("message")
+    def is_hello_world(cls, v):
+        if v != "hello world":
+            raise ValueError("Message must be hello world!")
+        return v
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        parsed_event = parse(model=HelloWorldModel, event=event)
+        return {"statusCode": 200, "body": f"Received message: {parsed_event.message}"}
+    except ValueError as e:
+        return {"statusCode": 400, "body": str(e)}

examples/parser/src/extending_built_in_models_with_json_mypy.py

@@ -0,0 +1,27 @@
+from aws_lambda_powertools.utilities.parser import BaseModel, field_validator, parse
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+class HelloWorldModel(BaseModel):
+    message: str
+    sender: str
+
+    @field_validator("*")
+    def has_whitespace(cls, v):
+        if " " not in v:
+            raise ValueError("Must have whitespace...")
+        return v
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        parsed_event = parse(model=HelloWorldModel, event=event)
+        return {
+            "statusCode": 200,
+            "body": f"Received message: {parsed_event.message}",
+        }
+    except ValueError as e:
+        return {
+            "statusCode": 400,
+            "body": str(e),
+        }

examples/parser/src/extending_built_in_models_with_json_validator.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel
+
+from aws_lambda_powertools.utilities.parser import event_parser
+
+
+class MyEvent(BaseModel):
+    id: int
+    name: str
+
+
+@event_parser(model=MyEvent)
+def lambda_handler(event: MyEvent, context):
+    # if your model is valid, you can return
+    return {"statusCode": 200, "body": f"Hello {event.name}, your ID is {event.id}"}

examples/parser/src/field_validator.py

@@ -0,0 +1,3 @@
+{
+    "body": "{\"order_id\": 12345, \"reason\": \"Changed my mind\"}"
+}

examples/parser/src/field_validator_all_values.py

@@ -0,0 +1,31 @@
+from pydantic import BaseModel, model_validator
+
+from aws_lambda_powertools.utilities.parser import parse
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+class UserModel(BaseModel):
+    username: str
+    parentid_1: str
+    parentid_2: str
+
+    @model_validator(mode="after")  # (1)!
+    def check_parents_match(cls, values):
+        pi1, pi2 = values.get("parentid_1"), values.get("parentid_2")
+        if pi1 is not None and pi2 is not None and pi1 != pi2:
+            raise ValueError("Parent ids do not match")
+        return values
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        parsed_event = parse(model=UserModel, event=event)
+        return {
+            "statusCode": 200,
+            "body": f"Received parent id from: {parsed_event.username}",
+        }
+    except ValueError as e:
+        return {
+            "statusCode": 400,
+            "body": str(e),
+        }

examples/parser/src/getting_started_with_parser.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel, ValidationError
+
+from aws_lambda_powertools.utilities.parser import parse
+
+
+# Define a Pydantic model for the expected structure of the input
+class MyEvent(BaseModel):
+    id: int
+    name: str
+
+
+def lambda_handler(event: dict, context):
+    try:
+        # Manually parse the incoming event into MyEvent model
+        parsed_event: MyEvent = parse(model=MyEvent, event=event)
+        return {"statusCode": 200, "body": f"Hello {parsed_event.name}, your ID is {parsed_event.id}"}
+    except ValidationError as e:
+        # Catch validation errors and return a 400 response
+        return {"statusCode": 400, "body": f"Validation error: {str(e)}"}

examples/parser/src/json_data_string.json

@@ -0,0 +1,41 @@
+from pydantic import BaseModel
+
+from aws_lambda_powertools.logging import Logger
+from aws_lambda_powertools.utilities.parser import parse
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+logger = Logger()
+
+
+class UserModel(BaseModel):
+    username: str
+    parentid_1: str
+    parentid_2: str
+
+
+def validate_user(event):
+    try:
+        user = parse(model=UserModel, event=event)
+        return {"statusCode": 200, "body": user.model_dump_json()}
+    except Exception as e:
+        logger.exception("Validation error")
+        return {"statusCode": 400, "body": str(e)}
+
+
+@logger.inject_lambda_context
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
+    logger.info("Received event", extra={"event": event})
+
+    result = validate_user(event)
+
+    if result["statusCode"] == 200:
+        user = UserModel.model_validate_json(result["body"])
+        logger.info("User validated successfully", extra={"username": user.username})
+
+        # Example of serialization
+        user_dict = user.model_dump()
+        user_json = user.model_dump_json()
+
+        logger.debug("User serializations", extra={"dict": user_dict, "json": user_json})
+
+    return result

examples/parser/src/model_validator.py

@@ -0,0 +1,26 @@
+{
+    "Records": [
+        {
+            "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
+            "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
+            "body": "Test message hello!",
+            "attributes": {
+                "ApproximateReceiveCount": "1",
+                "SentTimestamp": "1545082649183",
+                "SenderId": "AIDAIENQZJOLO23YVJ4VO",
+                "ApproximateFirstReceiveTimestamp": "1545082649185"
+            },
+            "messageAttributes": {
+                "testAttr": {
+                    "stringValue": "100",
+                    "binaryValue": "base64Str",
+                    "dataType": "Number"
+                }
+            },
+            "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
+            "eventSource": "aws:sqs",
+            "eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
+            "awsRegion": "us-east-2"
+        }
+    ]
+}

examples/parser/src/multiple_model_parsing.py

@@ -0,0 +1,17 @@
+from aws_lambda_powertools.utilities.parser import parse
+from aws_lambda_powertools.utilities.parser.models import SqsModel
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+def lambda_handler(event: dict, context: LambdaContext) -> list:
+    parsed_event = parse(model=SqsModel, event=event)
+
+    results = []
+    for record in parsed_event.Records:
+        results.append(
+            {
+                "message_id": record.messageId,
+                "body": record.body,
+            },
+        )
+    return results

examples/parser/src/parser_function.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Json
+
+from aws_lambda_powertools.utilities.parser import BaseEnvelope, event_parser
+from aws_lambda_powertools.utilities.parser.functions import (
+    _parse_and_validate_event,
+    _retrieve_or_set_model_from_cache,
+)
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+if TYPE_CHECKING:
+    from aws_lambda_powertools.utilities.parser.types import T
+
+
+class CancelOrder(BaseModel):
+    order_id: int
+    reason: str
+
+
+class CancelOrderModel(BaseModel):
+    body: Json[CancelOrder]
+
+
+class CustomEnvelope(BaseEnvelope):
+    def parse(self, data: dict[str, Any] | Any | None, model: type[T]):
+        adapter = _retrieve_or_set_model_from_cache(model=model)
+        return _parse_and_validate_event(data=data, adapter=adapter)
+
+
+@event_parser(model=CancelOrderModel, envelope=CustomEnvelope)
+def lambda_handler(event: CancelOrderModel, context: LambdaContext):
+    cancel_order: CancelOrder = event.body
+
+    assert cancel_order.order_id is not None
+
+    # Process the cancel order request
+    print(f"Cancelling order {cancel_order.order_id} for reason: {cancel_order.reason}")
+
+    return {
+        "statusCode": 200,
+        "body": f"Order {cancel_order.order_id} cancelled successfully",
+    }

examples/parser/src/serialization_parser.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from aws_lambda_powertools.utilities.parser import BaseEnvelope, BaseModel, event_parser
+from aws_lambda_powertools.utilities.parser.functions import (
+    _parse_and_validate_event,
+    _retrieve_or_set_model_from_cache,
+)
+from aws_lambda_powertools.utilities.typing import LambdaContext
+from aws_lambda_powertools.utilities.validation import validator
+
+if TYPE_CHECKING:
+    from aws_lambda_powertools.utilities.parser.types import T
+
+
+class CancelOrder(BaseModel):
+    order_id: int
+    reason: str
+
+
+class CancelOrderModel(BaseModel):
+    body: CancelOrder
+
+    @validator("body", pre=True)
+    def transform_body_to_dict(cls, value):
+        return json.loads(value) if isinstance(value, str) else value
+
+
+class CustomEnvelope(BaseEnvelope):
+    def parse(self, data: dict[str, Any] | Any | None, model: type[T]):
+        adapter = _retrieve_or_set_model_from_cache(model=model)
+        return _parse_and_validate_event(data=data, adapter=adapter)
+
+
+@event_parser(model=CancelOrderModel, envelope=CustomEnvelope)
+def lambda_handler(event: CancelOrderModel, context: LambdaContext):
+    cancel_order: CancelOrder = event.body
+
+    assert cancel_order.order_id is not None
+
+    # Process the cancel order request
+    print(f"Cancelling order {cancel_order.order_id} for reason: {cancel_order.reason}")
+
+    return {
+        "statusCode": 200,
+        "body": json.dumps({"message": f"Order {cancel_order.order_id} cancelled successfully"}),
+    }