feat(event-handler): add documentation and example for Field discriminator support

Author: dap0am

aws_lambda_powertools/event_handler/openapi/compat.py

@@ -3,6 +3,7 @@
 
 from collections import deque
 from collections.abc import Mapping, Sequence
+from copy import copy
 
 # MAINTENANCE: remove when deprecating Pydantic v1. Mypy doesn't handle two different code paths that import different
 # versions of a module, so we need to ignore errors here.
@@ -187,8 +188,6 @@ def model_rebuild(model: type[BaseModel]) -> None:
 
 def copy_field_info(*, field_info: FieldInfo, annotation: Any) -> FieldInfo:
     # Create a shallow copy of the field_info to preserve its type and all attributes
-    from copy import copy
-
     new_field = copy(field_info)
     # Update only the annotation to the new one
     new_field.annotation = annotation

docs/core/event_handler/api_gateway.md

@@ -568,6 +568,23 @@ You can use the `Form` type to tell the Event Handler that a parameter expects f
     --8<-- "examples/event_handler_rest/src/working_with_form_data.py"
     ```
 
+#### Discriminated unions
+
+!!! info "You must set `enable_validation=True` to use discriminated unions via type annotation."
+
+You can use Pydantic's `Field(discriminator="...")` with union types to create discriminated unions (also known as tagged unions). This allows the Event Handler to automatically determine which model to use based on a discriminator field in the request body.
+
+In the following example, we define two action types (`FooAction` and `BarAction`) that share a common discriminator field `action`. The Event Handler will automatically parse the request body and instantiate the correct model based on the `action` field value:
+
+```python hl_lines="3 4 8 31 36" title="discriminated_unions.py"
+--8<-- "examples/event_handler_rest/src/discriminated_unions.py"
+```
+
+1. `Field(discriminator="action")` tells Pydantic to use the `action` field to determine which model to instantiate
+2. `Body()` annotation tells the Event Handler to parse the request body using the discriminated union
+
+When you send a request with `{"action": "foo", "foo_data": "example"}`, the Event Handler will automatically create a `FooAction` instance. Similarly, `{"action": "bar", "bar_data": 42}` will create a `BarAction` instance.
+
 #### Supported types for response serialization
 
 With data validation enabled, we natively support serializing the following data types to JSON:

examples/event_handler_rest/src/discriminated_unions.py

@@ -0,0 +1,47 @@
+from typing import Literal, Union
+
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.event_handler.openapi.params import Body
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver(enable_validation=True)
+
+
+class FooAction(BaseModel):
+    """Action type for foo operations."""
+
+    action: Literal["foo"] = "foo"
+    foo_data: str
+
+
+class BarAction(BaseModel):
+    """Action type for bar operations."""
+
+    action: Literal["bar"] = "bar"
+    bar_data: int
+
+
+ActionType = Annotated[Union[FooAction, BarAction], Field(discriminator="action")]  # (1)!
+
+
+@app.post("/actions")
+@tracer.capture_method
+def handle_action(action: Annotated[ActionType, Body(description="Action to perform")]):  # (2)!
+    """Handle different action types using discriminated unions."""
+    if isinstance(action, FooAction):
+        return {"message": f"Handling foo action with data: {action.foo_data}"}
+    elif isinstance(action, BarAction):
+        return {"message": f"Handling bar action with data: {action.bar_data}"}
+
+
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_HTTP)
+@tracer.capture_lambda_handler
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
+    return app.resolve(event, context)