aws-lambda-powertools 3.0.1.dev2__py3-none-any.whl → 3.0.2.dev1__py3-none-any.whl

aws_lambda_powertools/event_handler/bedrock_agent.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 from typing import TYPE_CHECKING, Any, Callable
 
 from typing_extensions import override
@@ -10,10 +11,12 @@ from aws_lambda_powertools.event_handler.api_gateway import (
     ProxyEventType,
     ResponseBuilder,
 )
+from aws_lambda_powertools.event_handler.openapi.constants import DEFAULT_API_VERSION, DEFAULT_OPENAPI_VERSION
 
 if TYPE_CHECKING:
     from re import Match
 
+    from aws_lambda_powertools.event_handler.openapi.models import Contact, License, SecurityScheme, Server, Tag
     from aws_lambda_powertools.event_handler.openapi.types import OpenAPIResponse
     from aws_lambda_powertools.utilities.data_classes import BedrockAgentEvent
 
@@ -107,6 +110,8 @@ class BedrockAgentResolver(ApiGatewayResolver):
         include_in_schema: bool = True,
         middlewares: list[Callable[..., Any]] | None = None,
     ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+
+        openapi_extensions = None
         security = None
 
         return super().get(
@@ -122,6 +127,7 @@ class BedrockAgentResolver(ApiGatewayResolver):
             operation_id,
             include_in_schema,
             security,
+            openapi_extensions,
             middlewares,
         )
 
@@ -142,6 +148,7 @@ class BedrockAgentResolver(ApiGatewayResolver):
         include_in_schema: bool = True,
         middlewares: list[Callable[..., Any]] | None = None,
     ):
+        openapi_extensions = None
         security = None
 
         return super().post(
@@ -157,6 +164,7 @@ class BedrockAgentResolver(ApiGatewayResolver):
             operation_id,
             include_in_schema,
             security,
+            openapi_extensions,
             middlewares,
         )
 
@@ -177,6 +185,7 @@ class BedrockAgentResolver(ApiGatewayResolver):
         include_in_schema: bool = True,
         middlewares: list[Callable[..., Any]] | None = None,
     ):
+        openapi_extensions = None
         security = None
 
         return super().put(
@@ -192,6 +201,7 @@ class BedrockAgentResolver(ApiGatewayResolver):
             operation_id,
             include_in_schema,
             security,
+            openapi_extensions,
             middlewares,
         )
 
@@ -212,6 +222,7 @@ class BedrockAgentResolver(ApiGatewayResolver):
         include_in_schema: bool = True,
         middlewares: list[Callable] | None = None,
     ):
+        openapi_extensions = None
         security = None
 
         return super().patch(
@@ -227,6 +238,7 @@ class BedrockAgentResolver(ApiGatewayResolver):
             operation_id,
             include_in_schema,
             security,
+            openapi_extensions,
             middlewares,
         )
 
@@ -247,6 +259,7 @@ class BedrockAgentResolver(ApiGatewayResolver):
         include_in_schema: bool = True,
         middlewares: list[Callable[..., Any]] | None = None,
     ):
+        openapi_extensions = None
         security = None
 
         return super().delete(
@@ -262,6 +275,7 @@ class BedrockAgentResolver(ApiGatewayResolver):
             operation_id,
             include_in_schema,
             security,
+            openapi_extensions,
             middlewares,
         )
 
@@ -273,3 +287,110 @@ class BedrockAgentResolver(ApiGatewayResolver):
         if match.groupdict() and self.current_event.parameters:
             parameters = {parameter["name"]: parameter["value"] for parameter in self.current_event.parameters}
         return parameters
+
+    @override
+    def get_openapi_json_schema(  # type: ignore[override]
+        self,
+        *,
+        title: str = "Powertools API",
+        version: str = DEFAULT_API_VERSION,
+        openapi_version: str = DEFAULT_OPENAPI_VERSION,
+        summary: str | None = None,
+        description: str | None = None,
+        tags: list[Tag | str] | None = None,
+        servers: list[Server] | None = None,
+        terms_of_service: str | None = None,
+        contact: Contact | None = None,
+        license_info: License | None = None,
+        security_schemes: dict[str, SecurityScheme] | None = None,
+        security: list[dict[str, list[str]]] | None = None,
+    ) -> str:
+        """
+        Returns the OpenAPI schema as a JSON serializable dict.
+        Since Bedrock Agents only support OpenAPI 3.0.0, we convert OpenAPI 3.1.0 schemas
+        and enforce 3.0.0 compatibility for seamless integration.
+
+        Parameters
+        ----------
+        title: str
+            The title of the application.
+        version: str
+            The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API
+        openapi_version: str, default = "3.0.0"
+            The version of the OpenAPI Specification (which the document uses).
+        summary: str, optional
+            A short summary of what the application does.
+        description: str, optional
+            A verbose explanation of the application behavior.
+        tags: list[Tag, str], optional
+            A list of tags used by the specification with additional metadata.
+        servers: list[Server], optional
+            An array of Server Objects, which provide connectivity information to a target server.
+        terms_of_service: str, optional
+            A URL to the Terms of Service for the API. MUST be in the format of a URL.
+        contact: Contact, optional
+            The contact information for the exposed API.
+        license_info: License, optional
+            The license information for the exposed API.
+        security_schemes: dict[str, SecurityScheme]], optional
+            A declaration of the security schemes available to be used in the specification.
+        security: list[dict[str, list[str]]], optional
+            A declaration of which security mechanisms are applied globally across the API.
+
+        Returns
+        -------
+        str
+            The OpenAPI schema as a JSON serializable dict.
+        """
+        from aws_lambda_powertools.event_handler.openapi.compat import model_json
+
+        openapi_extensions = None
+
+        schema = super().get_openapi_schema(
+            title=title,
+            version=version,
+            openapi_version=openapi_version,
+            summary=summary,
+            description=description,
+            tags=tags,
+            servers=servers,
+            terms_of_service=terms_of_service,
+            contact=contact,
+            license_info=license_info,
+            security_schemes=security_schemes,
+            security=security,
+            openapi_extensions=openapi_extensions,
+        )
+        schema.openapi = "3.0.3"
+
+        # Transform OpenAPI 3.1 into 3.0
+        def inner(yaml_dict):
+            if isinstance(yaml_dict, dict):
+                if "anyOf" in yaml_dict and isinstance((anyOf := yaml_dict["anyOf"]), list):
+                    for i, item in enumerate(anyOf):
+                        if isinstance(item, dict) and item.get("type") == "null":
+                            anyOf.pop(i)
+                            yaml_dict["nullable"] = True
+                if "examples" in yaml_dict:
+                    examples = yaml_dict["examples"]
+                    del yaml_dict["examples"]
+                    if isinstance(examples, list) and len(examples):
+                        yaml_dict["example"] = examples[0]
+                for value in yaml_dict.values():
+                    inner(value)
+            elif isinstance(yaml_dict, list):
+                for item in yaml_dict:
+                    inner(item)
+
+        model = json.loads(
+            model_json(
+                schema,
+                by_alias=True,
+                exclude_none=True,
+                indent=2,
+            ),
+        )
+
+        inner(model)
+
+        return json.dumps(model)

aws_lambda_powertools/event_handler/exceptions.py

@@ -39,7 +39,7 @@ class NotFoundError(ServiceError):
 
 
 class InternalServerError(ServiceError):
-    """API Gateway and ALB Not Found Internal Server Error (500)"""
+    """API Gateway and ALB Internal Server Error (500)"""
 
     def __init__(self, message: str):
         super().__init__(HTTPStatus.INTERNAL_SERVER_ERROR, message)

aws_lambda_powertools/event_handler/graphql_appsync/_registry.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+class ResolverRegistry:
+    def __init__(self):
+        self.resolvers: dict[str, dict[str, Any]] = {}
+
+    def register(
+        self,
+        type_name: str = "*",
+        field_name: str | None = None,
+        raise_on_error: bool = False,
+        aggregate: bool = True,
+    ) -> Callable:
+        """Registers the resolver for field_name
+
+        Parameters
+        ----------
+        type_name : str
+            Type name
+        field_name : str
+            Field name
+        raise_on_error: bool
+            A flag indicating whether to raise an error when processing batches
+            with failed items. Defaults to False, which means errors are handled without raising exceptions.
+        aggregate: bool
+            A flag indicating whether the batch items should be processed at once or individually.
+            If True (default), the batch resolver will process all items in the batch as a single event.
+            If False, the batch resolver will process each item in the batch individually.
+
+        Return
+        ----------
+        Callable
+            A Callable
+        """
+
+        def _register(func) -> Callable:
+            logger.debug(f"Adding resolver `{func.__name__}` for field `{type_name}.{field_name}`")
+            self.resolvers[f"{type_name}.{field_name}"] = {
+                "func": func,
+                "raise_on_error": raise_on_error,
+                "aggregate": aggregate,
+            }
+            return func
+
+        return _register
+
+    def find_resolver(self, type_name: str, field_name: str) -> dict | None:
+        """Find resolver based on type_name and field_name
+
+        Parameters
+        ----------
+        type_name : str
+            Type name
+        field_name : str
+            Field name
+        Return
+        ----------
+        Optional[Dict]
+            A dictionary with the resolver and if raise exception on error
+        """
+        logger.debug(f"Looking for resolver for type={type_name}, field={field_name}.")
+        return self.resolvers.get(f"{type_name}.{field_name}", self.resolvers.get(f"*.{field_name}"))
+
+    def merge(self, other_registry: ResolverRegistry):
+        """Update current registry with incoming registry
+
+        Parameters
+        ----------
+        other_registry : ResolverRegistry
+            Registry to merge from
+        """
+        self.resolvers.update(**other_registry.resolvers)

aws_lambda_powertools/event_handler/graphql_appsync/base.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Callable
+
+
+class BaseRouter(ABC):
+    """Abstract base class for Router (resolvers)"""
+
+    @abstractmethod
+    def resolver(self, type_name: str = "*", field_name: str | None = None) -> Callable:
+        """
+        Retrieve a resolver function for a specific type and field.
+
+        Parameters
+        -----------
+        type_name: str
+            The name of the type.
+        field_name: str, optional
+            The name of the field (default is None).
+
+        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
+
+        app = AppSyncResolver()
+
+        @app.resolver(type_name="Query", field_name="getPost")
+        def related_posts(event: AppSyncResolverEvent) -> Optional[list]:
+            return {"success": "ok"}
+
+        def lambda_handler(event, context: LambdaContext) -> dict:
+            return app.resolve(event, context)
+        ```
+
+        Returns
+        -------
+        Callable
+            The resolver function.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def batch_resolver(
+        self,
+        type_name: str = "*",
+        field_name: str | None = None,
+        raise_on_error: bool = False,
+        aggregate: bool = True,
+    ) -> Callable:
+        """
+        Retrieve a batch resolver function for a specific type and field.
+
+        Parameters
+        -----------
+        type_name: str
+            The name of the type.
+        field_name: str, optional
+            The name of the field (default is None).
+        raise_on_error: bool
+            A flag indicating whether to raise an error when processing batches
+            with failed items. Defaults to False, which means errors are handled without raising exceptions.
+        aggregate: bool
+            A flag indicating whether the batch items should be processed at once or individually.
+            If True (default), the batch resolver will process all items in the batch as a single event.
+            If False, the batch resolver will process each item in the batch individually.
+
+        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
+
+        app = AppSyncResolver()
+
+        @app.batch_resolver(type_name="Query", field_name="getPost")
+        def related_posts(event: AppSyncResolverEvent, id) -> Optional[list]:
+            return {"post_id": id}
+
+        def lambda_handler(event, context: LambdaContext) -> dict:
+            return app.resolve(event, context)
+        ```
+
+        Returns
+        -------
+        Callable
+            The batch resolver function.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def async_batch_resolver(
+        self,
+        type_name: str = "*",
+        field_name: str | None = None,
+        raise_on_error: bool = False,
+        aggregate: bool = True,
+    ) -> Callable:
+        """
+        Retrieve a batch resolver function for a specific type and field and runs async.
+
+        Parameters
+        -----------
+        type_name: str
+            The name of the type.
+        field_name: str, optional
+            The name of the field (default is None).
+        raise_on_error: bool
+            A flag indicating whether to raise an error when processing batches
+            with failed items. Defaults to False, which means errors are handled without raising exceptions.
+        aggregate: bool
+            A flag indicating whether the batch items should be processed at once or individually.
+            If True (default), the batch resolver will process all items in the batch as a single event.
+            If False, the batch resolver will process each item in the batch individually.
+
+        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
+
+        app = AppSyncResolver()
+
+        @app.async_batch_resolver(type_name="Query", field_name="getPost")
+        async def related_posts(event: AppSyncResolverEvent, id) -> Optional[list]:
+            return {"post_id": id}
+
+        def lambda_handler(event, context: LambdaContext) -> dict:
+            return app.resolve(event, context)
+        ```
+
+        Returns
+        -------
+        Callable
+            The batch resolver function.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def append_context(self, **additional_context) -> None:
+        """
+        Appends context information available under any route.
+
+        Parameters
+        -----------
+        **additional_context: dict
+            Additional context key-value pairs to append.
+        """
+        raise NotImplementedError

aws_lambda_powertools/event_handler/graphql_appsync/exceptions.py

@@ -0,0 +1,10 @@
+class ResolverNotFoundError(Exception):
+    """
+    When a resolver is not found during a lookup.
+    """
+
+
+class InvalidBatchResponse(Exception):
+    """
+    When a batch response something different from a List
+    """

aws_lambda_powertools/event_handler/graphql_appsync/router.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable
+
+from aws_lambda_powertools.event_handler.graphql_appsync._registry import ResolverRegistry
+from aws_lambda_powertools.event_handler.graphql_appsync.base import BaseRouter
+
+if TYPE_CHECKING:
+    from aws_lambda_powertools.utilities.data_classes.appsync_resolver_event import AppSyncResolverEvent
+    from aws_lambda_powertools.utilities.typing.lambda_context import LambdaContext
+
+
+class Router(BaseRouter):
+    context: dict
+    current_batch_event: list[AppSyncResolverEvent] = []
+    current_event: AppSyncResolverEvent | None = None
+    lambda_context: LambdaContext | None = None
+
+    def __init__(self):
+        self.context = {}  # early init as customers might add context before event resolution
+        self._resolver_registry = ResolverRegistry()
+        self._batch_resolver_registry = ResolverRegistry()
+        self._async_batch_resolver_registry = ResolverRegistry()
+
+    def resolver(self, type_name: str = "*", field_name: str | None = None) -> Callable:
+        return self._resolver_registry.register(field_name=field_name, type_name=type_name)
+
+    def batch_resolver(
+        self,
+        type_name: str = "*",
+        field_name: str | None = None,
+        raise_on_error: bool = False,
+        aggregate: bool = True,
+    ) -> Callable:
+        return self._batch_resolver_registry.register(
+            field_name=field_name,
+            type_name=type_name,
+            raise_on_error=raise_on_error,
+            aggregate=aggregate,
+        )
+
+    def async_batch_resolver(
+        self,
+        type_name: str = "*",
+        field_name: str | None = None,
+        raise_on_error: bool = False,
+        aggregate: bool = True,
+    ) -> Callable:
+        return self._async_batch_resolver_registry.register(
+            field_name=field_name,
+            type_name=type_name,
+            raise_on_error=raise_on_error,
+            aggregate=aggregate,
+        )
+
+    def append_context(self, **additional_context):
+        """Append key=value data as routing context"""
+        self.context.update(**additional_context)
+
+    def clear_context(self):
+        """Resets routing context"""
+        self.context.clear()

aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

@@ -232,7 +232,7 @@ class OpenAPIValidationMiddleware(BaseMiddlewareHandler):
                 for k, v in res.items()
             }
         elif dataclasses.is_dataclass(res):
-            return dataclasses.asdict(res)
+            return dataclasses.asdict(res)  # type: ignore[call-overload]
         return res
 
     def _get_body(self, app: EventHandlerInstance) -> dict[str, Any]: