Merge branch 'develop' into feature/file-parameter-clean

Author: leandrodamascena

CHANGELOG.md

@@ -661,30 +661,36 @@ def _get_openapi_path(  # noqa PLR0912
                 else:
                     # Need to iterate to transform any 'model' into a 'schema'
                     for content_type, payload in response["content"].items():
-                        new_payload: OpenAPIResponseContentSchema
-
                         # Case 2.1: the 'content' has a model
                         if "model" in payload:
                             # Find the model in the dependant's extra models
+                            model_payload_typed = cast(OpenAPIResponseContentModel, payload)
                             return_field = next(
                                 filter(
-                                    lambda model: model.type_ is cast(OpenAPIResponseContentModel, payload)["model"],
+                                    lambda model: model.type_ is model_payload_typed["model"],
                                     self.dependant.response_extra_models,
                                 ),
                             )
                             if not return_field:
                                 raise AssertionError("Model declared in custom responses was not found")
 
-                            new_payload = self._openapi_operation_return(
+                            model_payload = self._openapi_operation_return(
                                 param=return_field,
                                 model_name_map=model_name_map,
                                 field_mapping=field_mapping,
                             )
 
+                            # Preserve existing fields like examples, encoding, etc.
+                            new_payload: OpenAPIResponseContentSchema = {}
+                            for key, value in payload.items():
+                                if key != "model":
+                                    new_payload[key] = value  # type: ignore[literal-required]
+                            new_payload.update(model_payload)  # Add/override with model schema
+
                         # Case 2.2: the 'content' has a schema
                         else:
                             # Do nothing! We already have what we need!
-                            new_payload = payload
+                            new_payload = cast(OpenAPIResponseContentSchema, payload)
 
                         response["content"][content_type] = new_payload
 

aws_lambda_powertools/event_handler/api_gateway.py

@@ -3,9 +3,7 @@
 
 from collections import deque
 from collections.abc import Mapping, Sequence
-
-# 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.
+from copy import copy
 from dataclasses import dataclass, is_dataclass
 from typing import TYPE_CHECKING, Any, Deque, FrozenSet, List, Set, Tuple, Union
 
@@ -80,9 +78,19 @@ def type_(self) -> Any:
         return self.field_info.annotation
 
     def __post_init__(self) -> None:
-        self._type_adapter: TypeAdapter[Any] = TypeAdapter(
-            Annotated[self.field_info.annotation, self.field_info],
-        )
+        # If the field_info.annotation is already an Annotated type with discriminator metadata,
+        # use it directly instead of wrapping it again
+        annotation = self.field_info.annotation
+        if (
+            get_origin(annotation) is Annotated
+            and hasattr(self.field_info, "discriminator")
+            and self.field_info.discriminator is not None
+        ):
+            self._type_adapter: TypeAdapter[Any] = TypeAdapter(annotation)
+        else:
+            self._type_adapter: TypeAdapter[Any] = TypeAdapter(
+                Annotated[annotation, self.field_info],
+            )
 
     def get_default(self) -> Any:
         if self.field_info.is_required():
@@ -176,7 +184,11 @@ def model_rebuild(model: type[BaseModel]) -> None:
 
 
 def copy_field_info(*, field_info: FieldInfo, annotation: Any) -> FieldInfo:
-    return type(field_info).from_annotation(annotation)
+    # Create a shallow copy of the field_info to preserve its type and all attributes
+    new_field = copy(field_info)
+    # Update only the annotation to the new one
+    new_field.annotation = annotation
+    return new_field
 
 
 def get_missing_field_error(loc: tuple[str, ...]) -> dict[str, Any]:

aws_lambda_powertools/event_handler/openapi/compat.py

@@ -1173,35 +1173,101 @@ def get_field_info_response_type(annotation, value) -> tuple[FieldInfo | None, A
     return get_field_info_and_type_annotation(inner_type, value, False, True)
 
 
+def _has_discriminator(field_info: FieldInfo) -> bool:
+    """Check if a FieldInfo has a discriminator."""
+    return hasattr(field_info, "discriminator") and field_info.discriminator is not None
+
+
+def _handle_discriminator_with_param(
+    annotations: list[FieldInfo],
+    annotation: Any,
+) -> tuple[FieldInfo | None, Any, bool]:
+    """
+    Handle the special case of Field(discriminator) + Body() combination.
+
+    Returns:
+        tuple of (powertools_annotation, type_annotation, has_discriminator_with_body)
+    """
+    field_obj = None
+    body_obj = None
+
+    for ann in annotations:
+        if isinstance(ann, Body):
+            body_obj = ann
+        elif _has_discriminator(ann):
+            field_obj = ann
+
+    if field_obj and body_obj:
+        # Use Body as the primary annotation, preserve full annotation for validation
+        return body_obj, annotation, True
+
+    raise AssertionError("Only one FieldInfo can be used per parameter")
+
+
+def _create_field_info(
+    powertools_annotation: FieldInfo,
+    type_annotation: Any,
+    has_discriminator_with_body: bool,
+) -> FieldInfo:
+    """Create or copy FieldInfo based on the annotation type."""
+    field_info: FieldInfo
+    if has_discriminator_with_body:
+        # For discriminator + Body case, create a new Body instance directly
+        field_info = Body()
+        field_info.annotation = type_annotation
+    else:
+        # Copy field_info because we mutate field_info.default later
+        field_info = copy_field_info(
+            field_info=powertools_annotation,
+            annotation=type_annotation,
+        )
+    return field_info
+
+
+def _set_field_default(field_info: FieldInfo, value: Any, is_path_param: bool) -> None:
+    """Set the default value for a field."""
+    if field_info.default not in [Undefined, Required]:
+        raise AssertionError("FieldInfo needs to have a default value of Undefined or Required")
+
+    if value is not inspect.Signature.empty:
+        if is_path_param:
+            raise AssertionError("Cannot use a FieldInfo as a path parameter and pass a value")
+        field_info.default = value
+    else:
+        field_info.default = Required
+
+
 def get_field_info_annotated_type(annotation, value, is_path_param: bool) -> tuple[FieldInfo | None, Any]:
     """
     Get the FieldInfo and type annotation from an Annotated type.
     """
-    field_info: FieldInfo | None = None
     annotated_args = get_args(annotation)
     type_annotation = annotated_args[0]
     powertools_annotations = [arg for arg in annotated_args[1:] if isinstance(arg, FieldInfo)]
 
-    if len(powertools_annotations) > 1:
-        raise AssertionError("Only one FieldInfo can be used per parameter")
-
-    powertools_annotation = next(iter(powertools_annotations), None)
+    # Determine which annotation to use
+    powertools_annotation: FieldInfo | None = None
+    has_discriminator_with_param = False
 
-    if isinstance(powertools_annotation, FieldInfo):
-        # Copy `field_info` because we mutate `field_info.default` later
-        field_info = copy_field_info(
-            field_info=powertools_annotation,
-            annotation=annotation,
+    if len(powertools_annotations) == 2:
+        powertools_annotation, type_annotation, has_discriminator_with_param = _handle_discriminator_with_param(
+            powertools_annotations,
+            annotation,
         )
-        if field_info.default not in [Undefined, Required]:
-            raise AssertionError("FieldInfo needs to have a default value of Undefined or Required")
+    elif len(powertools_annotations) > 1:
+        raise AssertionError("Only one FieldInfo can be used per parameter")
+    else:
+        powertools_annotation = next(iter(powertools_annotations), None)
 
-        if value is not inspect.Signature.empty:
-            if is_path_param:
-                raise AssertionError("Cannot use a FieldInfo as a path parameter and pass a value")
-            field_info.default = value
-        else:
-            field_info.default = Required
+    # Process the annotation if it exists
+    field_info: FieldInfo | None = None
+    if isinstance(powertools_annotation, FieldInfo):  # pragma: no cover
+        field_info = _create_field_info(powertools_annotation, type_annotation, has_discriminator_with_param)
+        _set_field_default(field_info, value, is_path_param)
+
+        # Preserve full annotated type for discriminated unions
+        if _has_discriminator(powertools_annotation):  # pragma: no cover
+            type_annotation = annotation  # pragma: no cover
 
     return field_info, type_annotation
 

aws_lambda_powertools/event_handler/openapi/params.py

@@ -63,14 +63,32 @@
 }
 
 
+class OpenAPIResponseHeader(TypedDict, total=False):
+    """OpenAPI Response Header Object"""
+
+    description: NotRequired[str]
+    schema: NotRequired[dict[str, Any]]
+    examples: NotRequired[dict[str, Any]]
+    style: NotRequired[str]
+    explode: NotRequired[bool]
+    allowReserved: NotRequired[bool]
+    deprecated: NotRequired[bool]
+
+
 class OpenAPIResponseContentSchema(TypedDict, total=False):
     schema: dict
+    examples: NotRequired[dict[str, Any]]
+    encoding: NotRequired[dict[str, Any]]
 
 
-class OpenAPIResponseContentModel(TypedDict):
+class OpenAPIResponseContentModel(TypedDict, total=False):
     model: Any
+    examples: NotRequired[dict[str, Any]]
+    encoding: NotRequired[dict[str, Any]]
 
 
-class OpenAPIResponse(TypedDict):
-    description: str
+class OpenAPIResponse(TypedDict, total=False):
+    description: str  # Still required
+    headers: NotRequired[dict[str, OpenAPIResponseHeader]]
     content: NotRequired[dict[str, OpenAPIResponseContentSchema | OpenAPIResponseContentModel]]
+    links: NotRequired[dict[str, Any]]

aws_lambda_powertools/event_handler/openapi/types.py

@@ -1,3 +1,3 @@
 """Exposes version constant to avoid circular dependencies."""
 
-VERSION = "3.20.0"
+VERSION = "3.20.1a0"

aws_lambda_powertools/shared/version.py

@@ -7,6 +7,8 @@ description: Optimize Lambda functions for better performance and reduced costs
 
 Optimize your Lambda functions for better performance, reduced cold start times, and lower costs. These techniques help minimize package size, improve startup speed, and reduce memory usage.
 
+Always validate your function's behavior after applying optimizations to ensure an optimization hasn't introduced any issues with your packages. For example, removal of directories that appear to be unnecessary, such as `docs`, can break some libraries.
+
 ## Reduce cold start times
 
 1. **Minimize package size** by excluding unnecessary files

docs/build_recipes/performance-optimization.md

@@ -428,6 +428,17 @@ We use the `Annotated` and OpenAPI `Body` type to instruct Event Handler that ou
     --8<-- "examples/event_handler_rest/src/validating_payload_subset_output.json"
     ```
 
+##### Discriminated unions
+
+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.
+
+```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
+
 #### Validating responses
 
 You can use `response_validation_error_http_code` to set a custom HTTP code for failed response validation. When this field is set, we will raise a `ResponseValidationError` instead of a `RequestValidationError`.
@@ -1482,6 +1493,9 @@ Each endpoint will be it's own Lambda function that is configured as a [Lambda i
 
 You can test your routes by passing a proxy event request with required params.
 
+???+ info
+    Fields such as headers and query strings are always delivered as strings when events reach Lambda. When testing your Lambda function with local events, we recommend using the sample events available in our [repository](https://github.com/aws-powertools/powertools-lambda-python/tree/develop/tests/events).
+
 === "API Gateway REST API"
 
     === "assert_rest_api_resolver_response.py"
@@ -1545,14 +1559,3 @@ You can test your routes by passing a proxy event request with required params.
 Chalice is a full featured microframework that manages application and infrastructure. This utility, however, is largely focused on routing to reduce boilerplate and expects you to setup and manage infrastructure with your framework of choice.
 
 That said, [Chalice has native integration with Lambda Powertools](https://aws.github.io/chalice/topics/middleware.html){target="_blank" rel="nofollow"} if you're looking for a more opinionated and web framework feature set.
-
-**What happened to `ApiGatewayResolver`?**
-
-It's been superseded by more explicit resolvers like `APIGatewayRestResolver`, `APIGatewayHttpResolver`, and `ALBResolver`.
-
-`ApiGatewayResolver` handled multiple types of event resolvers for convenience via `proxy_type` param. However,
-it made it impossible for static checkers like Mypy and IDEs IntelliSense to know what properties a `current_event` would have due to late bound resolution.
-
-This provided a suboptimal experience for customers not being able to find all properties available besides common ones between API Gateway REST, HTTP, and ALB - while manually annotating `app.current_event` would work it is not the experience we want to provide to customers.
-
-`ApiGatewayResolver` will be deprecated in v2 and have appropriate warnings as soon as we have a v2 draft.

docs/core/event_handler/api_gateway.md

@@ -15,7 +15,6 @@ find build/ -name "*.so.*" -exec strip --strip-debug {} \; 2>/dev/null || true
 rm -rf build/*/site-packages/*/tests/
 rm -rf build/*/site-packages/*/test/
 rm -rf build/*/site-packages/*/.git/
-rm -rf build/*/site-packages/*/docs/
 rm -rf build/*/site-packages/*/examples/
 rm -rf build/*/site-packages/*/*.md
 rm -rf build/*/site-packages/*/*.rst

examples/build_recipes/build_optimization/optimize-advanced.sh

@@ -7,8 +7,7 @@ find build/ -name "*.dist-info" -type d -exec rm -rf {} +
 find build/ -name "tests" -type d -exec rm -rf {} +
 find build/ -name "test_*" -delete
 
-# Remove documentation and examples
-find build/ -name "docs" -type d -exec rm -rf {} +
+# Remove examples
 find build/ -name "examples" -type d -exec rm -rf {} +
 
 echo "✅ Package optimized"