aws-lambda-powertools 3.28.0__tar.gz → 3.30.0__tar.gz

{aws_lambda_powertools-3.28.0 → aws_lambda_powertools-3.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: aws_lambda_powertools
-Version: 3.28.0
+Version: 3.30.0
 Summary: Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverless best practices and increase developer velocity.
 License: MIT
 Keywords: aws_lambda_powertools,aws,tracing,logging,lambda,powertools,feature_flags,idempotency,middleware
@@ -29,7 +29,7 @@ Provides-Extra: tracer
 Provides-Extra: validation
 Provides-Extra: valkey
 Requires-Dist: avro (>=1.12.0,<2.0.0) ; extra == "kafka-consumer-avro"
-Requires-Dist: aws-encryption-sdk (>=3.1.1,<5.0.0) ; extra == "all" or extra == "datamasking"
+Requires-Dist: aws-encryption-sdk (>=3.3.1,!=4.0.0,!=4.0.1,!=4.0.2,!=4.0.3,!=4.0.4,<5.0.0) ; extra == "all" or extra == "datamasking"
 Requires-Dist: aws-xray-sdk (>=2.8.0,<3.0.0) ; extra == "tracer" or extra == "all"
 Requires-Dist: boto3 (>=1.34.32,<2.0.0) ; extra == "aws-sdk"
 Requires-Dist: datadog-lambda (>=8.114.0,<9.0.0) ; extra == "datadog"

{aws_lambda_powertools-3.28.0 → aws_lambda_powertools-3.30.0}/aws_lambda_powertools/event_handler/__init__.py

@@ -18,7 +18,7 @@ from aws_lambda_powertools.event_handler.bedrock_agent_function import (
 )
 from aws_lambda_powertools.event_handler.depends import DependencyResolutionError, Depends
 from aws_lambda_powertools.event_handler.events_appsync.appsync_events import AppSyncEventsResolver
-from aws_lambda_powertools.event_handler.http_resolver import HttpResolverLocal
+from aws_lambda_powertools.event_handler.http_resolver import HttpResolver, HttpResolverLocal
 from aws_lambda_powertools.event_handler.lambda_function_url import (
     LambdaFunctionUrlResolver,
 )
@@ -39,6 +39,7 @@ __all__ = [
     "CORSConfig",
     "Depends",
     "DependencyResolutionError",
+    "HttpResolver",
     "HttpResolverLocal",
     "LambdaFunctionUrlResolver",
     "Request",

{aws_lambda_powertools-3.28.0 → aws_lambda_powertools-3.30.0}/aws_lambda_powertools/event_handler/api_gateway.py

@@ -613,6 +613,63 @@ class Route:
 
         self._middleware_stack_built = True
 
+    async def call_async(
+        self,
+        router_middlewares: list[Callable],
+        app: ApiGatewayResolver,
+        route_arguments: dict[str, str],
+    ) -> dict | tuple | Response:
+        from aws_lambda_powertools.event_handler.middlewares.async_utils import (
+            AsyncMiddlewareFrame,
+            _registered_api_adapter_async,
+        )
+
+        all_middlewares: list[Callable[..., Any]] = []
+
+        route_validation_enabled = (
+            self.enable_validation if self.enable_validation is not None else app._enable_validation
+        )
+
+        if route_validation_enabled and not hasattr(app, "_request_validation_middleware"):
+            from aws_lambda_powertools.event_handler.middlewares.openapi_validation import (
+                OpenAPIRequestValidationMiddleware,
+                OpenAPIResponseValidationMiddleware,
+            )
+
+            app._request_validation_middleware = OpenAPIRequestValidationMiddleware()
+            app._response_validation_middleware = OpenAPIResponseValidationMiddleware(
+                validation_serializer=app._serializer,
+                has_response_validation_error=app._has_response_validation_error,
+            )
+
+        if route_validation_enabled and hasattr(app, "_request_validation_middleware"):
+            all_middlewares.append(app._request_validation_middleware)
+
+        all_middlewares.extend(router_middlewares + self.middlewares)
+
+        if route_validation_enabled and hasattr(app, "_response_validation_middleware"):
+            all_middlewares.append(app._response_validation_middleware)
+
+        all_middlewares.append(_registered_api_adapter_async)
+
+        logger.debug(f"Building async middleware stack: {all_middlewares}")
+
+        if app._debug:
+            print(f"\nProcessing Route (async):::{self.func.__name__} ({app.context['_path']})")
+            print("\nAsync Middleware Stack:")
+            print("=================")
+            print("\n".join(getattr(item, "__name__", "Unknown") for item in all_middlewares))
+            print("=================")
+
+        app.append_context(_route_args=route_arguments)
+
+        # Build async chain from inside-out (not cached, avoids state conflicts with sync cache)
+        next_handler: Callable = self.func
+        for handler in reversed(all_middlewares):
+            next_handler = AsyncMiddlewareFrame(current_middleware=handler, next_middleware=next_handler)
+
+        return await next_handler(app)
+
     @property
     def dependant(self) -> Dependant:
         if self._dependant is None:
@@ -2509,6 +2566,154 @@ class ApiGatewayResolver(BaseRouter):
 
         return response
 
+    async def resolve_async(self, event: Mapping[str, Any], context: LambdaContext) -> dict[str, Any]:
+        """Async version of resolve() for native async handler support.
+
+        Use this method when your route handlers use async/await. The resolution
+        pipeline supports both sync and async handlers transparently.
+
+        Parameters
+        ----------
+        event: dict[str, Any]
+            Event
+        context: LambdaContext
+            Lambda context
+        Returns
+        -------
+        dict
+            Returns the dict response
+
+        Example
+        -------
+
+        ```python
+        import asyncio
+        from aws_lambda_powertools.event_handler import APIGatewayHttpResolver
+
+        app = APIGatewayHttpResolver()
+
+        @app.get("/async")
+        async def async_handler():
+            return {"message": "async works"}
+
+        def lambda_handler(event, context):
+            return asyncio.run(app.resolve_async(event, context))
+        ```
+        """
+        if isinstance(event, BaseProxyEvent):
+            warnings.warn(
+                "You don't need to serialize event to Event Source Data Class when using Event Handler; "
+                "see issue #1152",
+                stacklevel=2,
+            )
+            event = event.raw_event
+
+        if self._debug:
+            print(self._serializer(cast(dict, event)))
+
+        BaseRouter.current_event = self._to_proxy_event(cast(dict, event))
+        BaseRouter.lambda_context = context
+
+        response = (await self._resolve_async()).build(self.current_event, self._cors)
+
+        if self._debug:
+            print("\nProcessed Middlewares:")
+            print("======================")
+            print("\n".join(self.processed_stack_frames))
+            print("======================")
+
+        self.clear_context()
+
+        return response
+
+    async def _resolve_async(self) -> ResponseBuilder:
+        method = self.current_event.http_method.upper()
+        path = self._remove_prefix(self.current_event.path)
+
+        registered_routes = self._static_routes + self._dynamic_routes
+
+        for route in registered_routes:
+            if method != route.method:
+                continue
+            match_results: Match | None = route.rule.match(path)
+            if match_results:
+                logger.debug("Found a registered route. Calling async function")
+                self.append_context(_route=route, _path=path)
+
+                route_keys = self._convert_matches_into_route_keys(match_results)
+                return await self._call_route_async(route, route_keys)
+
+        return await self._handle_not_found_async(method=method, path=path)
+
+    async def _call_route_async(self, route: Route, route_arguments: dict[str, str]) -> ResponseBuilder:
+        try:
+            self._reset_processed_stack()
+
+            response = await route.call_async(
+                router_middlewares=self._router_middlewares,
+                app=self,
+                route_arguments=route_arguments,
+            )
+
+            return self._response_builder_class(
+                response=self._to_response(response),  # type: ignore[arg-type]
+                serializer=self._serializer,
+                route=route,
+            )
+        except Exception as exc:
+            response_builder = self._call_exception_handler(exc, route)
+            if response_builder:
+                return response_builder
+
+            logger.exception(exc)
+            if self._debug:
+                return self._response_builder_class(
+                    response=Response(
+                        status_code=500,
+                        content_type=content_types.TEXT_PLAIN,
+                        body="".join(traceback.format_exc()),
+                    ),
+                    serializer=self._serializer,
+                    route=route,
+                )
+
+            raise
+
+    async def _handle_not_found_async(self, method: str, path: str) -> ResponseBuilder:
+        logger.debug(f"No match found for path {path} and method {method}")
+
+        def not_found_handler():
+            _headers: dict[str, Any] = {}
+
+            if self._cors and method == "OPTIONS":
+                logger.debug("Pre-flight request detected. Returning CORS with empty response")
+                _headers["Access-Control-Allow-Methods"] = CORSConfig.build_allow_methods(self._cors_methods)
+                return Response(status_code=204, content_type=None, headers=_headers, body="")
+
+            custom_not_found_handler = self.exception_handler_manager.lookup_exception_handler(NotFoundError)
+            if custom_not_found_handler:
+                return custom_not_found_handler(NotFoundError())
+
+            return Response(
+                status_code=HTTPStatus.NOT_FOUND.value,
+                content_type=content_types.APPLICATION_JSON,
+                headers=_headers,
+                body={"statusCode": HTTPStatus.NOT_FOUND.value, "message": "Not found"},
+            )
+
+        route = Route(
+            rule=self._compile_regex(r".*"),
+            method=method,
+            path=path,
+            func=not_found_handler,
+            cors=self._cors_enabled,
+            compress=False,
+        )
+
+        self.append_context(_route=route, _path=path)
+
+        return await self._call_route_async(route=route, route_arguments={})
+
     def __call__(self, event, context) -> Any:
         return self.resolve(event, context)
 
@@ -3138,22 +3343,13 @@ class ALBResolver(ApiGatewayResolver):
         # ALB doesn't have a stage variable, so we just return an empty string
         return ""
 
-    # BedrockResponse is not used here but adding the same signature to keep strong typing
     @override
     def _to_response(self, result: dict | tuple | Response | BedrockResponse) -> Response | BedrockResponse:
         """Convert the route's result to a Response
 
         ALB requires a non-null body otherwise it converts as HTTP 5xx
-
-         3 main result types are supported:
-
-        - Dict[str, Any]: Rest api response with just the Dict to json stringify and content-type is set to
-          application/json
-        - Tuple[dict, int]: Same dict handling as above but with the option of including a status code
-        - Response: returned as is, and allows for more flexibility
         """
-
-        # NOTE: Minor override for early return on Response with null body for ALB
+        # ALB doesn't support null body - convert before building the final response
         if isinstance(result, Response) and result.body is None:
             logger.debug("ALB doesn't allow None responses; converting to empty string")
             result.body = ""

{aws_lambda_powertools-3.28.0 → aws_lambda_powertools-3.30.0}/aws_lambda_powertools/event_handler/appsync.py

@@ -392,7 +392,7 @@ class AppSyncResolver(Router):
         ----------
         type_name : str, optional
             GraphQL type e.g., Query, Mutation, by default "*" meaning any
-        field_name : Optional[str], optional
+        field_name : str | None, optional
             GraphQL field e.g., getTodo, createTodo, by default None
 
         Returns
@@ -447,7 +447,7 @@ class AppSyncResolver(Router):
         ----------
         type_name : str, optional
             GraphQL type e.g., Query, Mutation, by default "*" meaning any
-        field_name : Optional[str], optional
+        field_name : str | None, optional
             GraphQL field e.g., getTodo, createTodo, by default None
         raise_on_error : bool, optional
             Whether to fail entire batch upon error, or handle errors gracefully (None), by default False

{aws_lambda_powertools-3.28.0 → aws_lambda_powertools-3.30.0}/aws_lambda_powertools/event_handler/bedrock_agent.py

@@ -99,12 +99,17 @@ class BedrockAgentResolver(ApiGatewayResolver):
 
     current_event: BedrockAgentEvent
 
-    def __init__(self, debug: bool = False, enable_validation: bool = True):
+    def __init__(
+        self,
+        debug: bool = False,
+        enable_validation: bool = True,
+        serializer: Callable[[dict], str] | None = None,
+    ):
         super().__init__(
             proxy_type=ProxyEventType.BedrockAgentEvent,
             cors=None,
             debug=debug,
-            serializer=None,
+            serializer=serializer,
             strip_prefixes=None,
             enable_validation=enable_validation,
             json_body_deserializer=None,

{aws_lambda_powertools-3.28.0 → aws_lambda_powertools-3.30.0}/aws_lambda_powertools/event_handler/graphql_appsync/_registry.py

@@ -64,7 +64,7 @@ class ResolverRegistry:
             Field name
         Return
         ----------
-        Optional[Dict]
+        dict | None
             A dictionary with the resolver and if raise exception on error
         """
         logger.debug(f"Looking for resolver for type={type_name}, field={field_name}.")

{aws_lambda_powertools-3.28.0 → aws_lambda_powertools-3.30.0}/aws_lambda_powertools/event_handler/graphql_appsync/base.py

@@ -25,8 +25,6 @@ class BaseRouter(ABC):
         Examples
         --------
         ```python
-        from typing import Optional
-
         from aws_lambda_powertools.event_handler import AppSyncResolver
         from aws_lambda_powertools.utilities.data_classes import AppSyncResolverEvent
         from aws_lambda_powertools.utilities.typing import LambdaContext
@@ -34,7 +32,7 @@ class BaseRouter(ABC):
         app = AppSyncResolver()
 
         @app.resolver(type_name="Query", field_name="getPost")
-        def related_posts(event: AppSyncResolverEvent) -> Optional[list]:
+        def related_posts(event: AppSyncResolverEvent) -> list | None:
             return {"success": "ok"}
 
         def lambda_handler(event, context: LambdaContext) -> dict:
@@ -76,8 +74,6 @@ class BaseRouter(ABC):
         Examples
         --------
         ```python
-        from typing import Optional
-
         from aws_lambda_powertools.event_handler import AppSyncResolver
         from aws_lambda_powertools.utilities.data_classes import AppSyncResolverEvent
         from aws_lambda_powertools.utilities.typing import LambdaContext
@@ -85,7 +81,7 @@ class BaseRouter(ABC):
         app = AppSyncResolver()
 
         @app.batch_resolver(type_name="Query", field_name="getPost")
-        def related_posts(event: AppSyncResolverEvent, id) -> Optional[list]:
+        def related_posts(event: AppSyncResolverEvent, id) -> list | None:
             return {"post_id": id}
 
         def lambda_handler(event, context: LambdaContext) -> dict:
@@ -127,8 +123,6 @@ class BaseRouter(ABC):
         Examples
         --------
         ```python
-        from typing import Optional
-
         from aws_lambda_powertools.event_handler import AppSyncResolver
         from aws_lambda_powertools.utilities.data_classes import AppSyncResolverEvent
         from aws_lambda_powertools.utilities.typing import LambdaContext
@@ -136,7 +130,7 @@ class BaseRouter(ABC):
         app = AppSyncResolver()
 
         @app.async_batch_resolver(type_name="Query", field_name="getPost")
-        async def related_posts(event: AppSyncResolverEvent, id) -> Optional[list]:
+        async def related_posts(event: AppSyncResolverEvent, id) -> list | None:
             return {"post_id": id}
 
         def lambda_handler(event, context: LambdaContext) -> dict:

{aws_lambda_powertools-3.28.0 → aws_lambda_powertools-3.30.0}/aws_lambda_powertools/event_handler/http_resolver.py

@@ -1,10 +1,6 @@
 from __future__ import annotations
 
-import asyncio
 import base64
-import inspect
-import threading
-import warnings
 from typing import TYPE_CHECKING, Any, Callable
 from urllib.parse import parse_qs
 
@@ -12,8 +8,6 @@ from aws_lambda_powertools.event_handler.api_gateway import (
     ApiGatewayResolver,
     BaseRouter,
     ProxyEventType,
-    Response,
-    Route,
 )
 from aws_lambda_powertools.shared.headers_serializer import BaseHeadersSerializer
 from aws_lambda_powertools.utilities.data_classes.common import BaseProxyEvent
@@ -167,21 +161,16 @@ class MockLambdaContext:
 
 class HttpResolverLocal(ApiGatewayResolver):
     """
-    ASGI-compatible HTTP resolver for local development and testing.
+    ASGI-compatible HTTP resolver.
 
-    This resolver is designed specifically for local development workflows.
-    It allows you to run your Powertools application locally with any ASGI server
+    It allows you to run your Powertools application with any ASGI server
     (uvicorn, hypercorn, daphne, etc.) while maintaining full compatibility with Lambda.
 
     The same code works in both environments - locally via ASGI and in Lambda via the handler.
+    If your Lambda is behind Lambda Web Adapter or any other HTTP proxy, it works seamlessly.
 
     Supports both sync and async route handlers.
 
-    WARNING
-    -------
-    This is intended for local development and testing only.
-    The API may change in future releases. Do not use in production environments.
-
     Example
     -------
     ```python
@@ -215,11 +204,6 @@ class HttpResolverLocal(ApiGatewayResolver):
         strip_prefixes: list[str | Any] | None = None,
         enable_validation: bool = False,
     ):
-        warnings.warn(
-            "HttpResolverLocal is intended for local development and testing only. "
-            "The API may change in future releases. Do not use in production environments.",
-            stacklevel=2,
-        )
         super().__init__(
             proxy_type=ProxyEventType.APIGatewayProxyEvent,  # Use REST API format internally
             cors=cors,
@@ -240,177 +224,14 @@ class HttpResolverLocal(ApiGatewayResolver):
         """Return the base path for HTTP resolver (no stage prefix)."""
         return ""
 
-    async def _resolve_async(self) -> dict:
-        """Async version of resolve that supports async handlers."""
-        method = self.current_event.http_method.upper()
-        path = self._remove_prefix(self.current_event.path)
+    async def _resolve_async(self) -> dict:  # type: ignore[override]
+        """Thin async resolver: delegates entirely to the parent and serializes to dict.
 
-        registered_routes = self._static_routes + self._dynamic_routes
-
-        for route in registered_routes:
-            if method != route.method:
-                continue
-            match_results = route.rule.match(path)
-            if match_results:
-                self.append_context(_route=route, _path=path)
-                route_keys = self._convert_matches_into_route_keys(match_results)
-                return await self._call_route_async(route, route_keys)
-
-        # Handle not found
-        return await self._handle_not_found_async()
-
-    async def _call_route_async(self, route: Route, route_arguments: dict[str, str]) -> dict:
-        """Call route handler, supporting both sync and async handlers."""
-        from aws_lambda_powertools.event_handler.api_gateway import ResponseBuilder
-
-        try:
-            self._reset_processed_stack()
-
-            # Get the route args (may be modified by validation middleware)
-            self.append_context(_route_args=route_arguments)
-
-            # Run middleware chain (sync for now, handlers can be async)
-            response = await self._run_middleware_chain_async(route)
-
-            response_builder: ResponseBuilder = ResponseBuilder(
-                response=response,
-                serializer=self._serializer,
-                route=route,
-            )
-
-            return response_builder.build(self.current_event, self._cors)
-
-        except Exception as exc:
-            exc_response_builder = self._call_exception_handler(exc, route)
-            if exc_response_builder:
-                return exc_response_builder.build(self.current_event, self._cors)
-            raise
-
-    async def _run_middleware_chain_async(self, route: Route) -> Response:
-        """Run the middleware chain, awaiting async handlers."""
-        # Build middleware list
-        all_middlewares: list[Callable[..., Any]] = []
-
-        # Determine if validation should be enabled for this route
-        # If route has explicit enable_validation setting, use it; otherwise, use resolver's global setting
-        route_validation_enabled = (
-            route.enable_validation if route.enable_validation is not None else self._enable_validation
-        )
-
-        if route_validation_enabled and hasattr(self, "_request_validation_middleware"):
-            all_middlewares.append(self._request_validation_middleware)
-
-        all_middlewares.extend(self._router_middlewares + route.middlewares)
-
-        if route_validation_enabled and hasattr(self, "_response_validation_middleware"):
-            all_middlewares.append(self._response_validation_middleware)
-
-        # Create the final handler that calls the route function
-        async def final_handler(app):
-            route_args = app.context.get("_route_args", {})
-            result = route.func(**route_args)
-
-            # Await if coroutine
-            if inspect.iscoroutine(result):
-                result = await result
-
-            return self._to_response(result)
-
-        # Build middleware chain from end to start
-        next_handler = final_handler
-
-        for middleware in reversed(all_middlewares):
-            next_handler = self._wrap_middleware_async(middleware, next_handler)
-
-        return await next_handler(self)
-
-    def _wrap_middleware_async(self, middleware: Callable, next_handler: Callable) -> Callable:
-        """Wrap a middleware to work in async context.
-
-        For sync middlewares, we split execution into pre/post phases around the
-        call to next(). The sync middleware runs its pre-processing (e.g. request
-        validation), then we intercept the next() call, await the async handler,
-        and resume the middleware with the real response so post-processing
-        (e.g. response validation) sees the actual data.
+        The parent's _resolve_async handles route matching, CORS preflight, not-found
+        logic, and exception handling. The only adaptation needed here is converting
+        the returned ResponseBuilder into the dict format that asgi_handler expects.
         """
-
-        async def wrapped(app):
-            if inspect.iscoroutinefunction(middleware):
-                return await middleware(app, next_handler)
-
-            # We use an Event to coordinate: the sync middleware runs in a thread,
-            # calls sync_next which signals us to resolve the async handler,
-            # then waits for the real response.
-            middleware_called_next = asyncio.Event()
-            next_app_holder: list = []
-            real_response_holder: list = []
-            middleware_result_holder: list = []
-            middleware_error_holder: list = []
-
-            def sync_next(app):
-                next_app_holder.append(app)
-                middleware_called_next.set()
-                # Block this thread until the real response is available
-                event = threading.Event()
-                next_app_holder.append(event)
-                event.wait()
-                return real_response_holder[0]
-
-            def run_middleware():
-                try:
-                    result = middleware(app, sync_next)
-                    middleware_result_holder.append(result)
-                except Exception as e:
-                    middleware_error_holder.append(e)
-
-            thread = threading.Thread(target=run_middleware, daemon=True)
-            thread.start()
-
-            # Wait for the middleware to call next()
-            await middleware_called_next.wait()
-
-            # Now resolve the async next_handler
-            real_response = await next_handler(next_app_holder[0])
-            real_response_holder.append(real_response)
-
-            # Signal the thread that the response is ready
-            threading_event = next_app_holder[1]
-            threading_event.set()
-
-            # Wait for the middleware thread to finish
-            thread.join()
-
-            if middleware_error_holder:
-                raise middleware_error_holder[0]
-
-            return middleware_result_holder[0]
-
-        return wrapped
-
-    async def _handle_not_found_async(self) -> dict:
-        """Handle 404 responses, using custom not_found handler if registered."""
-        from http import HTTPStatus
-
-        from aws_lambda_powertools.event_handler.api_gateway import ResponseBuilder
-        from aws_lambda_powertools.event_handler.exceptions import NotFoundError
-
-        # Check for custom not_found handler
-        custom_not_found_handler = self.exception_handler_manager.lookup_exception_handler(NotFoundError)
-        if custom_not_found_handler:
-            response = custom_not_found_handler(NotFoundError())
-        else:
-            response = Response(
-                status_code=HTTPStatus.NOT_FOUND.value,
-                content_type="application/json",
-                body={"statusCode": HTTPStatus.NOT_FOUND.value, "message": "Not found"},
-            )
-
-        response_builder: ResponseBuilder = ResponseBuilder(
-            response=response,
-            serializer=self._serializer,
-            route=None,
-        )
-
+        response_builder = await super()._resolve_async()
         return response_builder.build(self.current_event, self._cors)
 
     async def asgi_handler(self, scope: dict, receive: Callable, send: Callable) -> None:
@@ -519,3 +340,6 @@ class HttpResolverLocal(ApiGatewayResolver):
                 "body": body_bytes,
             },
         )
+
+
+HttpResolver = HttpResolverLocal