Merging from develop

Author: leandrodamascena

CHANGELOG.md

@@ -14,9 +14,28 @@
 
 ## Maintenance
 
+* **ci:** new pre-release 3.8.1a3 ([#6259](https://github.com/aws-powertools/powertools-lambda-python/issues/6259))
+* **ci:** new pre-release 3.8.1a0 ([#6244](https://github.com/aws-powertools/powertools-lambda-python/issues/6244))
+* **ci:** new pre-release 3.8.1a4 ([#6268](https://github.com/aws-powertools/powertools-lambda-python/issues/6268))
+* **ci:** new pre-release 3.8.1a1 ([#6250](https://github.com/aws-powertools/powertools-lambda-python/issues/6250))
+* **ci:** new pre-release 3.8.1a2 ([#6253](https://github.com/aws-powertools/powertools-lambda-python/issues/6253))
+* **ci:** new pre-release 3.8.1a5 ([#6276](https://github.com/aws-powertools/powertools-lambda-python/issues/6276))
+* **deps:** bump squidfunk/mkdocs-material from `047452c` to `479a06a` in /docs ([#6261](https://github.com/aws-powertools/powertools-lambda-python/issues/6261))
+* **deps-dev:** bump mkdocs-material from 9.6.7 to 9.6.8 ([#6264](https://github.com/aws-powertools/powertools-lambda-python/issues/6264))
+* **deps-dev:** bump aws-cdk from 2.1003.0 to 2.1004.0 ([#6262](https://github.com/aws-powertools/powertools-lambda-python/issues/6262))
+* **deps-dev:** bump boto3-stubs from 1.37.10 to 1.37.11 ([#6252](https://github.com/aws-powertools/powertools-lambda-python/issues/6252))
+* **deps-dev:** bump cfn-lint from 1.29.1 to 1.30.0 ([#6263](https://github.com/aws-powertools/powertools-lambda-python/issues/6263))
+* **deps-dev:** bump cfn-lint from 1.28.0 to 1.29.1 ([#6249](https://github.com/aws-powertools/powertools-lambda-python/issues/6249))
+* **deps-dev:** bump boto3-stubs from 1.37.8 to 1.37.10 ([#6248](https://github.com/aws-powertools/powertools-lambda-python/issues/6248))
+* **deps-dev:** bump aws-cdk-lib from 2.182.0 to 2.183.0 ([#6257](https://github.com/aws-powertools/powertools-lambda-python/issues/6257))
+* **deps-dev:** bump boto3-stubs from 1.37.11 to 1.37.12 ([#6266](https://github.com/aws-powertools/powertools-lambda-python/issues/6266))
+* **deps-dev:** bump filelock from 3.17.0 to 3.18.0 ([#6270](https://github.com/aws-powertools/powertools-lambda-python/issues/6270))
 * **deps-dev:** bump ruff from 0.9.9 to 0.9.10 ([#6241](https://github.com/aws-powertools/powertools-lambda-python/issues/6241))
 * **deps-dev:** bump cdklabs-generative-ai-cdk-constructs from 0.1.295 to 0.1.296 ([#6240](https://github.com/aws-powertools/powertools-lambda-python/issues/6240))
 * **deps-dev:** bump boto3-stubs from 1.37.7 to 1.37.8 ([#6239](https://github.com/aws-powertools/powertools-lambda-python/issues/6239))
+* **deps-dev:** bump aws-cdk-aws-lambda-python-alpha from 2.183.0a0 to 2.184.1a0 ([#6271](https://github.com/aws-powertools/powertools-lambda-python/issues/6271))
+* **deps-dev:** bump aws-cdk-lib from 2.183.0 to 2.184.1 ([#6272](https://github.com/aws-powertools/powertools-lambda-python/issues/6272))
+* **deps-dev:** bump aws-cdk-aws-lambda-python-alpha from 2.182.0a0 to 2.183.0a0 ([#6258](https://github.com/aws-powertools/powertools-lambda-python/issues/6258))
 
 
 <a name="v3.8.0"></a>

aws_lambda_powertools/event_handler/api_gateway.py

@@ -24,7 +24,11 @@
     DEFAULT_OPENAPI_TITLE,
     DEFAULT_OPENAPI_VERSION,
 )
-from aws_lambda_powertools.event_handler.openapi.exceptions import RequestValidationError, SchemaValidationError
+from aws_lambda_powertools.event_handler.openapi.exceptions import (
+    RequestValidationError,
+    ResponseValidationError,
+    SchemaValidationError,
+)
 from aws_lambda_powertools.event_handler.openapi.types import (
     COMPONENT_REF_PREFIX,
     METHODS_WITH_BODY,
@@ -1501,6 +1505,7 @@ def __init__(
         serializer: Callable[[dict], str] | None = None,
         strip_prefixes: list[str | Pattern] | None = None,
         enable_validation: bool = False,
+        response_validation_error_http_code: HTTPStatus | int | None = None,
     ):
         """
         Parameters
@@ -1520,6 +1525,8 @@ def __init__(
             Each prefix can be a static string or a compiled regex pattern
         enable_validation: bool | None
             Enables validation of the request body against the route schema, by default False.
+        response_validation_error_http_code
+            Sets the returned status code if response is not validated. enable_validation must be True.
         """
         self._proxy_type = proxy_type
         self._dynamic_routes: list[Route] = []
@@ -1536,6 +1543,11 @@ def __init__(
         self.processed_stack_frames = []
         self._response_builder_class = ResponseBuilder[BaseProxyEvent]
         self.openapi_config = OpenAPIConfig()  # starting an empty dataclass
+        self._has_response_validation_error = response_validation_error_http_code is not None
+        self._response_validation_error_http_code = self._validate_response_validation_error_http_code(
+            response_validation_error_http_code,
+            enable_validation,
+        )
 
         # Allow for a custom serializer or a concise json serialization
         self._serializer = serializer or partial(json.dumps, separators=(",", ":"), cls=Encoder)
@@ -1545,7 +1557,36 @@ def __init__(
 
             # Note the serializer argument: only use custom serializer if provided by the caller
             # Otherwise, fully rely on the internal Pydantic based mechanism to serialize responses for validation.
-            self.use([OpenAPIValidationMiddleware(validation_serializer=serializer)])
+            self.use(
+                [
+                    OpenAPIValidationMiddleware(
+                        validation_serializer=serializer,
+                        has_response_validation_error=self._has_response_validation_error,
+                    ),
+                ],
+            )
+
+    def _validate_response_validation_error_http_code(
+        self,
+        response_validation_error_http_code: HTTPStatus | int | None,
+        enable_validation: bool,
+    ) -> HTTPStatus:
+        if response_validation_error_http_code and not enable_validation:
+            msg = "'response_validation_error_http_code' cannot be set when enable_validation is False."
+            raise ValueError(msg)
+
+        if (
+            not isinstance(response_validation_error_http_code, HTTPStatus)
+            and response_validation_error_http_code is not None
+        ):
+
+            try:
+                response_validation_error_http_code = HTTPStatus(response_validation_error_http_code)
+            except ValueError:
+                msg = f"'{response_validation_error_http_code}' must be an integer representing an HTTP status code."
+                raise ValueError(msg) from None
+
+        return response_validation_error_http_code or HTTPStatus.UNPROCESSABLE_ENTITY
 
     def get_openapi_schema(
         self,
@@ -1723,7 +1764,7 @@ def _get_openapi_servers(servers: list[Server] | None) -> list[Server]:
 
         # If the 'servers' property is not provided or is an empty array,
         # the default behavior is to return a Server Object with a URL value of "/".
-        return servers if servers else [Server(url="/")]
+        return servers or [Server(url="/")]
 
     @staticmethod
     def _get_openapi_security(
@@ -2225,10 +2266,7 @@ def _get_base_path(self) -> str:
     @staticmethod
     def _has_debug(debug: bool | None = None) -> bool:
         # It might have been explicitly switched off (debug=False)
-        if debug is not None:
-            return debug
-
-        return powertools_dev_is_set()
+        return debug if debug is not None else powertools_dev_is_set()
 
     @staticmethod
     def _compile_regex(rule: str, base_regex: str = _ROUTE_REGEX):
@@ -2341,7 +2379,7 @@ def _path_starts_with(path: str, prefix: str):
         if not isinstance(prefix, str) or prefix == "":
             return False
 
-        return path.startswith(prefix + "/")
+        return path.startswith(f"{prefix}/")
 
     def _handle_not_found(self, method: str, path: str) -> ResponseBuilder:
         """Called when no matching route was found and includes support for the cors preflight response"""
@@ -2484,6 +2522,21 @@ def _call_exception_handler(self, exp: Exception, route: Route) -> ResponseBuild
                 route=route,
             )
 
+        # OpenAPIValidationMiddleware will only raise ResponseValidationError when
+        # 'self._response_validation_error_http_code' is not None
+        if isinstance(exp, ResponseValidationError):
+            http_code = self._response_validation_error_http_code
+            errors = [{"loc": e["loc"], "type": e["type"]} for e in exp.errors()]
+            return self._response_builder_class(
+                response=Response(
+                    status_code=http_code.value,
+                    content_type=content_types.APPLICATION_JSON,
+                    body={"statusCode": self._response_validation_error_http_code, "detail": errors},
+                ),
+                serializer=self._serializer,
+                route=route,
+            )
+
         if isinstance(exp, ServiceError):
             return self._response_builder_class(
                 response=Response(
@@ -2597,8 +2650,9 @@ def _get_fields_from_routes(routes: Sequence[Route]) -> list[ModelField]:
             if route.dependant.response_extra_models:
                 responses_from_routes.extend(route.dependant.response_extra_models)
 
-        flat_models = list(responses_from_routes + request_fields_from_routes + body_fields_from_routes)
-        return flat_models
+        return list(
+            responses_from_routes + request_fields_from_routes + body_fields_from_routes,
+        )
 
 
 class Router(BaseRouter):
@@ -2696,6 +2750,7 @@ def __init__(
         serializer: Callable[[dict], str] | None = None,
         strip_prefixes: list[str | Pattern] | None = None,
         enable_validation: bool = False,
+        response_validation_error_http_code: HTTPStatus | int | None = None,
     ):
         """Amazon API Gateway REST and HTTP API v1 payload resolver"""
         super().__init__(
@@ -2705,6 +2760,7 @@ def __init__(
             serializer,
             strip_prefixes,
             enable_validation,
+            response_validation_error_http_code,
         )
 
     def _get_base_path(self) -> str:
@@ -2778,6 +2834,7 @@ def __init__(
         serializer: Callable[[dict], str] | None = None,
         strip_prefixes: list[str | Pattern] | None = None,
         enable_validation: bool = False,
+        response_validation_error_http_code: HTTPStatus | int | None = None,
     ):
         """Amazon API Gateway HTTP API v2 payload resolver"""
         super().__init__(
@@ -2787,6 +2844,7 @@ def __init__(
             serializer,
             strip_prefixes,
             enable_validation,
+            response_validation_error_http_code,
         )
 
     def _get_base_path(self) -> str:
@@ -2815,9 +2873,18 @@ def __init__(
         serializer: Callable[[dict], str] | None = None,
         strip_prefixes: list[str | Pattern] | None = None,
         enable_validation: bool = False,
+        response_validation_error_http_code: HTTPStatus | int | None = None,
     ):
         """Amazon Application Load Balancer (ALB) resolver"""
-        super().__init__(ProxyEventType.ALBEvent, cors, debug, serializer, strip_prefixes, enable_validation)
+        super().__init__(
+            ProxyEventType.ALBEvent,
+            cors,
+            debug,
+            serializer,
+            strip_prefixes,
+            enable_validation,
+            response_validation_error_http_code,
+        )
 
     def _get_base_path(self) -> str:
         # ALB doesn't have a stage variable, so we just return an empty string

aws_lambda_powertools/event_handler/lambda_function_url.py

@@ -8,6 +8,8 @@
 )
 
 if TYPE_CHECKING:
+    from http import HTTPStatus
+
     from aws_lambda_powertools.event_handler import CORSConfig
     from aws_lambda_powertools.utilities.data_classes import LambdaFunctionUrlEvent
 
@@ -57,6 +59,7 @@ def __init__(
         serializer: Callable[[dict], str] | None = None,
         strip_prefixes: list[str | Pattern] | None = None,
         enable_validation: bool = False,
+        response_validation_error_http_code: HTTPStatus | int | None = None,
     ):
         super().__init__(
             ProxyEventType.LambdaFunctionUrlEvent,
@@ -65,6 +68,7 @@ def __init__(
             serializer,
             strip_prefixes,
             enable_validation,
+            response_validation_error_http_code,
         )
 
     def _get_base_path(self) -> str:

aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

@@ -17,7 +17,7 @@
 )
 from aws_lambda_powertools.event_handler.openapi.dependant import is_scalar_field
 from aws_lambda_powertools.event_handler.openapi.encoders import jsonable_encoder
-from aws_lambda_powertools.event_handler.openapi.exceptions import RequestValidationError
+from aws_lambda_powertools.event_handler.openapi.exceptions import RequestValidationError, ResponseValidationError
 from aws_lambda_powertools.event_handler.openapi.params import Param
 
 if TYPE_CHECKING:
@@ -58,7 +58,11 @@ def get_todos(): list[Todo]:
     ```
     """
 
-    def __init__(self, validation_serializer: Callable[[Any], str] | None = None):
+    def __init__(
+        self,
+        validation_serializer: Callable[[Any], str] | None = None,
+        has_response_validation_error: bool = False,
+    ):
         """
         Initialize the OpenAPIValidationMiddleware.
 
@@ -67,8 +71,13 @@ def __init__(self, validation_serializer: Callable[[Any], str] | None = None):
         validation_serializer : Callable, optional
             Optional serializer to use when serializing the response for validation.
             Use it when you have a custom type that cannot be serialized by the default jsonable_encoder.
+
+        has_response_validation_error: bool, optional
+            Optional flag used to distinguish between payload and validation errors.
+            By setting this flag to True, ResponseValidationError will be raised if response could not be validated.
         """
         self._validation_serializer = validation_serializer
+        self._has_response_validation_error = has_response_validation_error
 
     def handler(self, app: EventHandlerInstance, next_middleware: NextMiddleware) -> Response:
         logger.debug("OpenAPIValidationMiddleware handler")
@@ -164,6 +173,8 @@ def _serialize_response(
             errors: list[dict[str, Any]] = []
             value = _validate_field(field=field, value=response_content, loc=("response",), existing_errors=errors)
             if errors:
+                if self._has_response_validation_error:
+                    raise ResponseValidationError(errors=_normalize_errors(errors), body=response_content)
                 raise RequestValidationError(errors=_normalize_errors(errors), body=response_content)
 
             if hasattr(field, "serialize"):

aws_lambda_powertools/event_handler/openapi/exceptions.py

@@ -23,6 +23,16 @@ def __init__(self, errors: Sequence[Any], *, body: Any = None) -> None:
         self.body = body
 
 
+class ResponseValidationError(ValidationException):
+    """
+    Raised when the response body does not match the OpenAPI schema
+    """
+
+    def __init__(self, errors: Sequence[Any], *, body: Any = None) -> None:
+        super().__init__(errors)
+        self.body = body
+
+
 class SerializationError(Exception):
     """
     Base exception for all encoding errors

aws_lambda_powertools/event_handler/vpc_lattice.py

@@ -8,6 +8,8 @@
 )
 
 if TYPE_CHECKING:
+    from http import HTTPStatus
+
     from aws_lambda_powertools.event_handler import CORSConfig
     from aws_lambda_powertools.utilities.data_classes import VPCLatticeEvent, VPCLatticeEventV2
 
@@ -53,9 +55,18 @@ def __init__(
         serializer: Callable[[dict], str] | None = None,
         strip_prefixes: list[str | Pattern] | None = None,
         enable_validation: bool = False,
+        response_validation_error_http_code: HTTPStatus | int | None = None,
     ):
         """Amazon VPC Lattice resolver"""
-        super().__init__(ProxyEventType.VPCLatticeEvent, cors, debug, serializer, strip_prefixes, enable_validation)
+        super().__init__(
+            ProxyEventType.VPCLatticeEvent,
+            cors,
+            debug,
+            serializer,
+            strip_prefixes,
+            enable_validation,
+            response_validation_error_http_code,
+        )
 
     def _get_base_path(self) -> str:
         return ""
@@ -102,9 +113,18 @@ def __init__(
         serializer: Callable[[dict], str] | None = None,
         strip_prefixes: list[str | Pattern] | None = None,
         enable_validation: bool = False,
+        response_validation_error_http_code: HTTPStatus | int | None = None,
     ):
         """Amazon VPC Lattice resolver"""
-        super().__init__(ProxyEventType.VPCLatticeEventV2, cors, debug, serializer, strip_prefixes, enable_validation)
+        super().__init__(
+            ProxyEventType.VPCLatticeEventV2,
+            cors,
+            debug,
+            serializer,
+            strip_prefixes,
+            enable_validation,
+            response_validation_error_http_code,
+        )
 
     def _get_base_path(self) -> str:
         return ""

aws_lambda_powertools/shared/version.py

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

aws_lambda_powertools/utilities/parser/models/s3.py

@@ -53,7 +53,7 @@ class S3Message(BaseModel):
     s3SchemaVersion: str
     configurationId: str
     bucket: S3Bucket
-    object: S3Object  # noqa: A003,VNE003
+    object: S3Object  # noqa: A003
 
 
 class S3EventNotificationObjectModel(BaseModel):
@@ -71,7 +71,7 @@ class S3EventNotificationEventBridgeBucketModel(BaseModel):
 class S3EventNotificationEventBridgeDetailModel(BaseModel):
     version: str
     bucket: S3EventNotificationEventBridgeBucketModel
-    object: S3EventNotificationObjectModel  # noqa: A003,VNE003
+    object: S3EventNotificationObjectModel  # noqa: A003
     request_id: str = Field(..., alias="request-id")
     requester: str
     source_ip_address: Optional[str] = Field(None, alias="source-ip-address")

docs/Dockerfile

@@ -1,5 +1,5 @@
 # v9.1.18
-FROM squidfunk/mkdocs-material@sha256:047452c6641137c9caa3647d050ddb7fa67b59ed48cc67ec3a4995f3d360ab32
+FROM squidfunk/mkdocs-material@sha256:479a06a8f5a320a9b2b17e72cb7012388d66ea71a8568235cfa072eb152bc30c
 # pip-compile --generate-hashes --output-file=requirements.txt requirements.in
 COPY requirements.txt /tmp/
 RUN pip install --require-hashes -r /tmp/requirements.txt