fix(docs): extract code snippets into dedicated python files and fix examples

docs_examples/core/api_gateway/app_alb.py

@@ -0,0 +1,20 @@
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import ALBResolver
+from aws_lambda_powertools.logging import correlation_paths
+
+tracer = Tracer()
+logger = Logger()
+app = ALBResolver()
+
+
+@app.get("/hello")
+@tracer.capture_method
+def get_hello_universe():
+    return {"message": "hello universe"}
+
+
+# You can continue to use other utilities just as before
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.APPLICATION_LOAD_BALANCER)
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_binary.py

@@ -0,0 +1,16 @@
+import os
+from pathlib import Path
+
+from aws_lambda_powertools.event_handler.api_gateway import APIGatewayRestResolver, Response
+
+app = APIGatewayRestResolver()
+logo_file: bytes = Path(os.getenv("LAMBDA_TASK_ROOT") + "/logo.svg").read_bytes()
+
+
+@app.get("/logo")
+def get_logo():
+    return Response(status_code=200, content_type="image/svg+xml", body=logo_file)
+
+
+def lambda_handler(event, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_catch_all_routes.py

@@ -0,0 +1,12 @@
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+
+app = APIGatewayRestResolver()
+
+
+@app.get(".+")
+def catch_any_route_after_any():
+    return {"path_received": app.current_event.path}
+
+
+def lambda_handler(event, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_compress.py

@@ -0,0 +1,12 @@
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+
+app = APIGatewayRestResolver()
+
+
+@app.get("/hello", compress=True)
+def get_hello_you():
+    return {"message": "hello universe"}
+
+
+def lambda_handler(event, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_cors.py

@@ -0,0 +1,28 @@
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler.api_gateway import APIGatewayRestResolver, CORSConfig
+from aws_lambda_powertools.logging import correlation_paths
+
+tracer = Tracer()
+logger = Logger()
+
+cors_config = CORSConfig(allow_origin="https://example.com", max_age=300)
+app = APIGatewayRestResolver(cors=cors_config)
+
+
+@app.get("/hello/<name>")
+@tracer.capture_method
+def get_hello_you(name):
+    return {"message": f"hello {name}"}
+
+
+@app.get("/hello", cors=False)  # optionally exclude CORS from response, if needed
+@tracer.capture_method
+def get_hello_no_cors_needed():
+    return {"message": "hello, no CORS needed for this path ;)"}
+
+
+# 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, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_custom_domain.py

@@ -0,0 +1,19 @@
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver(strip_prefixes=["/payment"])
+
+
+@app.get("/subscriptions/<subscription>")
+@tracer.capture_method
+def get_subscription(subscription):
+    return {"subscription_id": subscription}
+
+
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_custom_serializer.py

@@ -0,0 +1,44 @@
+import json
+from enum import Enum
+from json import JSONEncoder
+from typing import Dict
+
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+
+
+class CustomEncoder(JSONEncoder):
+    """Your customer json encoder"""
+
+    def default(self, obj):
+        if isinstance(obj, Enum):
+            return obj.value
+        try:
+            iterable = iter(obj)
+        except TypeError:
+            pass
+        else:
+            return sorted(iterable)
+        return JSONEncoder.default(self, obj)
+
+
+def custom_serializer(obj) -> str:
+    """Your custom serializer function APIGatewayRestResolver will use"""
+    return json.dumps(obj, cls=CustomEncoder)
+
+
+# Assigning your custom serializer
+app = APIGatewayRestResolver(serializer=custom_serializer)
+
+
+class Color(Enum):
+    RED = 1
+    BLUE = 2
+
+
+@app.get("/colors")
+def get_color() -> Dict:
+    return {
+        # Color.RED will be serialized to 1 as expected now
+        "color": Color.RED,
+        "variations": {"light", "dark"},
+    }

docs_examples/core/api_gateway/app_debug.py

@@ -0,0 +1,12 @@
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+
+app = APIGatewayRestResolver(debug=True)
+
+
+@app.get("/hello")
+def get_hello_universe():
+    return {"message": "hello universe"}
+
+
+def lambda_handler(event, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_dynamic_routes.py

@@ -0,0 +1,20 @@
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver()
+
+
+@app.get("/hello/<name>")
+@tracer.capture_method
+def get_hello_you(name):
+    return {"message": f"hello {name}"}
+
+
+# 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, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_exception_handler.py

@@ -0,0 +1,35 @@
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import content_types
+from aws_lambda_powertools.event_handler.api_gateway import APIGatewayRestResolver, Response
+from aws_lambda_powertools.logging import correlation_paths
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver()
+
+
+@app.exception_handler(ValueError)
+def handle_value_error(ex: ValueError):
+    metadata = {"path": app.current_event.path}
+    logger.error(f"Malformed request: {ex}", extra=metadata)
+
+    return Response(
+        status_code=400,
+        content_type=content_types.TEXT_PLAIN,
+        body="Invalid request",
+    )
+
+
+@app.get("/hello")
+@tracer.capture_method
+def hello_name():
+    name = app.current_event.get_query_string_value(name="name")
+    if name is not None:
+        raise ValueError("name query string must be present")
+    return {"message": f"hello {name}"}
+
+
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_headers.py

@@ -0,0 +1,15 @@
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+
+app = APIGatewayRestResolver()
+
+
+@app.get("/hello")
+def get_hello_you():
+    headers_as_dict = app.current_event.headers
+    name = app.current_event.get_header_value(name="X-Name", default_value="")
+
+    return {"message": f"hello {name}"}
+
+
+def lambda_handler(event, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_http_api.py

@@ -0,0 +1,20 @@
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayHttpResolver
+from aws_lambda_powertools.logging import correlation_paths
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayHttpResolver()
+
+
+@app.get("/hello")
+@tracer.capture_method
+def get_hello_universe():
+    return {"message": "hello universe"}
+
+
+# You can continue to use other utilities just as before
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_HTTP)
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_http_errors.py

@@ -0,0 +1,51 @@
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.event_handler.exceptions import (
+    BadRequestError,
+    InternalServerError,
+    NotFoundError,
+    ServiceError,
+    UnauthorizedError,
+)
+from aws_lambda_powertools.logging import correlation_paths
+
+tracer = Tracer()
+logger = Logger()
+
+app = APIGatewayRestResolver()
+
+
+@app.get(rule="/bad-request-error")
+def bad_request_error():
+    # HTTP  400
+    raise BadRequestError("Missing required parameter")
+
+
+@app.get(rule="/unauthorized-error")
+def unauthorized_error():
+    # HTTP 401
+    raise UnauthorizedError("Unauthorized")
+
+
+@app.get(rule="/not-found-error")
+def not_found_error():
+    # HTTP 404
+    raise NotFoundError
+
+
+@app.get(rule="/internal-server-error")
+def internal_server_error():
+    # HTTP 500
+    raise InternalServerError("Internal server error")
+
+
+@app.get(rule="/service-error", cors=True)
+def service_error():
+    raise ServiceError(502, "Something went wrong!")
+    # alternatively
+    # from http import HTTPStatus
+    # raise ServiceError(HTTPStatus.BAD_GATEWAY.value, "Something went wrong)
+
+
+def handler(event, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_http_methods.py

@@ -0,0 +1,22 @@
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver()
+
+
+# Only POST HTTP requests to the path /hello will route to this function
+@app.post("/hello")
+@tracer.capture_method
+def get_hello_you():
+    name = app.current_event.json_body.get("name")
+    return {"message": f"hello {name}"}
+
+
+# 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, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_multi_http_methods.py

@@ -0,0 +1,22 @@
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver()
+
+
+# PUT and POST HTTP requests to the path /hello will route to this function
+@app.route("/hello", method=["PUT", "POST"])
+@tracer.capture_method
+def get_hello_you():
+    name = app.current_event.json_body.get("name")
+    return {"message": f"hello {name}"}
+
+
+# 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, context):
+    return app.resolve(event, context)

docs_examples/core/api_gateway/app_nested_routes.py

@@ -0,0 +1,20 @@
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver()
+
+
+@app.get("/<message>/<name>")
+@tracer.capture_method
+def get_message(message, name):
+    return {"message": f"{message}, {name}"}
+
+
+# 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, context):
+    return app.resolve(event, context)