docs(event-handler): Initial markdown docs

Author: michaelbrewer

aws_lambda_powertools/utilities/data_classes/__init__.py

@@ -1,3 +1,7 @@
+"""
+Event Source Data Classes utility provides classes self-describing Lambda event sources.
+"""
+
 from .alb_event import ALBEvent
 from .api_gateway_proxy_event import APIGatewayProxyEvent, APIGatewayProxyEventV2
 from .appsync_resolver_event import AppSyncResolverEvent

aws_lambda_powertools/utilities/event_handler/__init__.py

@@ -1,3 +1,7 @@
+"""
+Event handler decorators for common Lambda events
+"""
+
 from .appsync import AppSyncResolver
 
 __all__ = ["AppSyncResolver"]

docs/index.md

@@ -152,6 +152,7 @@ aws serverlessrepo list-application-versions \
 | [Event source data classes](./utilities/data_classes) | Data classes describing the schema of common Lambda event triggers
 | [Parser](./utilities/parser) | Data parsing and deep validation using Pydantic
 | [Idempotency](./utilities/idempotency) | Idempotent Lambda handler
+| [Event handler](./utilities/event_handler) | Event handler decorators for common Lambda events
 
 ## Environment variables
 

docs/utilities/event_handler.md

@@ -0,0 +1,152 @@
+---
+title: Event Handler
+description: Utility
+---
+
+Event handler decorators for common Lambda events
+
+
+### AppSync Resolver Decorator
+
+> New in 1.14.0
+
+
+=== "app.py"
+
+    ```python hl_lines="1-3 6 8-9 13-14 18-19 23 25"
+    from aws_lambda_powertools.logging import Logger, correlation_paths
+    from aws_lambda_powertools.utilities.data_classes import AppSyncResolverEvent
+    from aws_lambda_powertools.utilities.event_handler import AppSyncResolver
+
+    logger = Logger()
+    app = AppSyncResolver()
+
+    @app.resolver(type_name="Query", field_name="listLocations", include_event=True)
+    def list_locations(event: AppSyncResolverEvent, page: int = 0, size: int = 10):
+        # Your logic to fetch locations
+        ...
+
+    @app.resolver(type_name="Merchant", field_name="extraInfo", include_event=True)
+    def get_extra_info(event: AppSyncResolverEvent):
+        # Can use "event.source" to filter within the parent context
+        ...
+
+    @app.resolver(field_name="commonField")
+    def common_field():
+        # Would match all fieldNames matching 'commonField'
+        ...
+
+    @logger.inject_lambda_context(correlation_id_path=correlation_paths.APPSYNC_RESOLVER)
+    def handle(event, context):
+        app.resolve(event, context)
+    ```
+=== "schema.graphql"
+
+    ```graphql hl_lines="7-10 17-18 22-23"
+    @model
+    type Merchant
+    {
+        id: String!
+        name: String!
+        description: String
+        # Resolves to `get_extra_info`
+        extraInfo: ExtraInfo @function(name: "merchantInformation-${env}")
+        # Resolves to `common_field`
+        commonField: String  @function(name: "merchantInformation-${env}")
+    }
+
+    type Location {
+        id: ID!
+        name: String!
+        address: Address
+        # Resolves to `common_field`
+        commonField: String  @function(name: "merchantInformation-${env}")
+    }
+
+    type Query {
+      # List of locations resolves to `list_locations`
+      listLocations(page: Int, size: Int): [Location] @function(name: "merchantInformation-${env}")
+    }
+    ```
+=== "Example list_locations event"
+
+    ```json hl_lines="2-7"
+    {
+      "typeName": "Query",
+      "fieldName": "listLocations",
+      "arguments": {
+        "page": 2,
+        "size": 1
+      },
+      "identity": {
+        "claims": {
+          "iat": 1615366261
+          ...
+        },
+        "username": "mike",
+        ...
+      },
+      "request": {
+        "headers": {
+          "x-amzn-trace-id": "Root=1-60488877-0b0c4e6727ab2a1c545babd0",
+          "x-forwarded-for": "127.0.0.1"
+          ...
+        }
+      },
+      ...
+    }
+    ```
+
+=== "Example get_extra_info event"
+
+    ```json hl_lines="2 3"
+    {
+      "typeName": "Merchant",
+      "fieldName": "extraInfo",
+      "arguments": {
+      },
+      "identity": {
+        "claims": {
+          "iat": 1615366261
+          ...
+        },
+        "username": "mike",
+        ...
+      },
+      "request": {
+        "headers": {
+          "x-amzn-trace-id": "Root=1-60488877-0b0c4e6727ab2a1c545babd0",
+          "x-forwarded-for": "127.0.0.1"
+          ...
+        }
+      },
+      ...
+    }
+    ```
+
+=== "Example common_field event"
+
+    ```json hl_lines="2 3"
+    {
+      "typeName": "Merchant",
+      "fieldName": "commonField",
+      "arguments": {
+      },
+      "identity": {
+        "claims": {
+          "iat": 1615366261
+          ...
+        },
+        "username": "mike",
+        ...
+      },
+      "request": {
+        "headers": {
+          "x-amzn-trace-id": "Root=1-60488877-0b0c4e6727ab2a1c545babd0",
+          "x-forwarded-for": "127.0.0.1"
+          ...
+        }
+      },
+      ...
+    }
+    ```

mkdocs.yml

@@ -18,6 +18,7 @@ nav:
       - utilities/data_classes.md
       - utilities/parser.md
       - utilities/idempotency.md
+      - utilities/event_handler.md
 
 theme:
   name: material