docs(event-handler): snippets split, improved, and lint (#1279)

Author: heitorlessa

docs/core/event_handler/api_gateway.md

@@ -14,6 +14,9 @@ Logger provides an opinionated logger with output structured as JSON.
 
 ## Getting started
 
+???+ tip
+    All examples shared in this documentation are available within the [project repository](https://github.com/awslabs/aws-lambda-powertools-python/tree/develop/examples){target="_blank"}.
+
 Logger requires two settings:
 
 | Setting           | Description                                                         | Environment variable      | Constructor parameter |

docs/core/logger.md

@@ -28,6 +28,9 @@ If you're new to Amazon CloudWatch, there are two terminologies you must be awar
 
 ## Getting started
 
+???+ tip
+    All examples shared in this documentation are available within the [project repository](https://github.com/awslabs/aws-lambda-powertools-python/tree/develop/examples){target="_blank"}.
+
 Metric has two global settings that will be used across all metrics emitted:
 
 | Setting              | Description                                                                     | Environment variable           | Constructor parameter |

docs/core/metrics.md

@@ -16,6 +16,9 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray Python SDK](https://github.
 
 ## Getting started
 
+???+ tip
+    All examples shared in this documentation are available within the [project repository](https://github.com/awslabs/aws-lambda-powertools-python/tree/develop/examples){target="_blank"}.
+
 ### Permissions
 
 Before your use this utility, your AWS Lambda function [must have permissions](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html#services-xray-permissions) to send traces to AWS X-Ray.

docs/core/tracer.md

@@ -0,0 +1,56 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: Hello world event handler API Gateway
+
+Globals:
+  Api:
+    TracingEnabled: true
+    Cors: # see CORS section
+      AllowOrigin: "'https://example.com'"
+      AllowHeaders: "'Content-Type,Authorization,X-Amz-Date'"
+      MaxAge: "'300'"
+    BinaryMediaTypes: # see Binary responses section
+      - "*~1*" # converts to */* for any binary type
+  Function:
+    Timeout: 5
+    Runtime: python3.8
+    Tracing: Active
+    Environment:
+      Variables:
+        LOG_LEVEL: INFO
+        POWERTOOLS_LOGGER_SAMPLE_RATE: 0.1
+        POWERTOOLS_LOGGER_LOG_EVENT: true
+        POWERTOOLS_SERVICE_NAME: example
+
+Resources:
+  ApiFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: app.lambda_handler
+      CodeUri: api_handler/
+      Description: API handler function
+      Events:
+        AnyApiEvent:
+          Type: Api
+          Properties:
+            # NOTE: this is a catch-all rule to simplify the documentation.
+            # explicit routes and methods are recommended for prod instead (see below)
+            Path: /{proxy+} # Send requests on any path to the lambda function
+            Method: ANY # Send requests using any http method to the lambda function
+
+
+        # GetAllTodos:
+        #   Type: Api
+        #   Properties:
+        #     Path: /todos
+        #     Method: GET
+        # GetTodoById:
+        #   Type: Api
+        #   Properties:
+        #     Path: /todos/{todo_id}
+        #     Method: GET
+        # CreateTodo:
+        #   Type: Api
+        #   Properties:
+        #     Path: /todos
+        #     Method: POST

examples/event_handler_rest/sam/template.yaml

@@ -0,0 +1,40 @@
+from typing import Optional
+
+import requests
+from requests import Response
+
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver()
+
+
+@app.get("/todos")
+@tracer.capture_method
+def get_todos():
+    todo_id: str = app.current_event.get_query_string_value(name="id", default_value="")
+    # alternatively
+    _: Optional[str] = app.current_event.query_string_parameters.get("id")
+
+    # Payload
+    _: Optional[str] = app.current_event.body  # raw str | None
+
+    endpoint = "https://jsonplaceholder.typicode.com/todos"
+    if todo_id:
+        endpoint = f"{endpoint}/{todo_id}"
+
+    todos: Response = requests.get(endpoint)
+    todos.raise_for_status()
+
+    return {"todos": todos.json()}
+
+
+# You can continue to use other utilities just as before
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
+@tracer.capture_lambda_handler
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
+    return app.resolve(event, context)

examples/event_handler_rest/src/accessing_request_details.py

@@ -0,0 +1,30 @@
+import requests
+from requests import Response
+
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver()
+
+
+@app.get("/todos")
+@tracer.capture_method
+def get_todos():
+    endpoint = "https://jsonplaceholder.typicode.com/todos"
+
+    api_key: str = app.current_event.get_header_value(name="X-Api-Key", case_sensitive=True, default_value="")
+    todos: Response = requests.get(endpoint, headers={"X-Api-Key": api_key})
+    todos.raise_for_status()
+
+    return {"todos": todos.json()}
+
+
+# You can continue to use other utilities just as before
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
+@tracer.capture_lambda_handler
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
+    return app.resolve(event, context)

examples/event_handler_rest/src/accessing_request_details_headers.py

@@ -0,0 +1,28 @@
+from dataclasses import dataclass
+
+import assert_http_response_module
+import pytest
+
+
+@pytest.fixture
+def lambda_context():
+    @dataclass
+    class LambdaContext:
+        function_name: str = "test"
+        memory_limit_in_mb: int = 128
+        invoked_function_arn: str = "arn:aws:lambda:eu-west-1:123456789012:function:test"
+        aws_request_id: str = "da658bd3-2d6f-4e7b-8ec2-937234644fdc"
+
+    return LambdaContext()
+
+
+def test_lambda_handler(lambda_context):
+    minimal_event = {
+        "path": "/todos",
+        "httpMethod": "GET",
+        "requestContext": {"requestId": "227b78aa-779d-47d4-a48e-ce62120393b8"},  # correlation ID
+    }
+
+    ret = assert_http_response_module.lambda_handler(minimal_event, lambda_context)
+    assert ret["statusCode"] == 200
+    assert ret["body"] != ""

examples/event_handler_rest/src/assert_http_response.py

@@ -0,0 +1,27 @@
+import requests
+from requests import Response
+
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver()
+
+
+@app.get("/todos")
+@tracer.capture_method
+def get_todos():
+    todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos")
+    todos.raise_for_status()
+
+    return {"todos": todos.json()[:10]}
+
+
+# You can continue to use other utilities just as before
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
+@tracer.capture_lambda_handler
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
+    return app.resolve(event, context)

examples/event_handler_rest/src/assert_http_response_module.py

@@ -0,0 +1,8 @@
+{
+    "headers": {
+        "Accept": "image/svg+xml"
+    },
+    "resource": "/logo",
+    "path": "/logo",
+    "httpMethod": "GET"
+}