feat(event_handler): Add new EventHandler for Async Lambda

CHANGELOG.md

@@ -119,6 +119,128 @@
 * **docs:** enable privacy plugin in docs ([#6036](https://github.com/aws-powertools/powertools-lambda-python/issues/6036))
 
 
+<a name="v3.5.0"></a>
+## [v3.5.0] - 2025-01-28
+## Bug Fixes
+
+* **security:** fix encryption_context handling in data masking operations ([#6074](https://github.com/aws-powertools/powertools-lambda-python/issues/6074))
+
+## Documentation
+
+* **roadmap:** update roadmap ([#6077](https://github.com/aws-powertools/powertools-lambda-python/issues/6077))
+
+## Maintenance
+
+* **ci:** new pre-release 3.6.1a0 ([#6084](https://github.com/aws-powertools/powertools-lambda-python/issues/6084))
+* **deps:** bump aws-actions/configure-aws-credentials from 4.0.3 to 4.1.0 ([#6082](https://github.com/aws-powertools/powertools-lambda-python/issues/6082))
+* **deps-dev:** bump coverage from 7.6.11 to 7.6.12 ([#6080](https://github.com/aws-powertools/powertools-lambda-python/issues/6080))
+* **deps-dev:** bump mkdocstrings-python from 1.14.6 to 1.15.0 ([#6079](https://github.com/aws-powertools/powertools-lambda-python/issues/6079))
+* **deps-dev:** bump boto3-stubs from 1.36.16 to 1.36.17 ([#6078](https://github.com/aws-powertools/powertools-lambda-python/issues/6078))
+
+
+<a name="v3.6.0"></a>
+## [v3.6.0] - 2025-02-11
+## Bug Fixes
+
+* **docs:** typo in a service name in Event Handler ([#5944](https://github.com/aws-powertools/powertools-lambda-python/issues/5944))
+* **logger:** child logger must respect log level ([#5950](https://github.com/aws-powertools/powertools-lambda-python/issues/5950))
+
+## Code Refactoring
+
+* **metrics:** Improve type annotations for metrics decorator ([#6000](https://github.com/aws-powertools/powertools-lambda-python/issues/6000))
+
+## Documentation
+
+* **api:** migrating the event handler utility to mkdocstrings ([#6023](https://github.com/aws-powertools/powertools-lambda-python/issues/6023))
+* **api:** migrating the metrics utility to mkdocstrings ([#6022](https://github.com/aws-powertools/powertools-lambda-python/issues/6022))
+* **api:** migrating the logger utility to mkdocstrings ([#6021](https://github.com/aws-powertools/powertools-lambda-python/issues/6021))
+* **api:** migrating the Middleware Factory utility to mkdocstrings ([#6019](https://github.com/aws-powertools/powertools-lambda-python/issues/6019))
+* **api:** migrating the tracer utility to mkdocstrings ([#6017](https://github.com/aws-powertools/powertools-lambda-python/issues/6017))
+* **api:** migrating the batch utility to mkdocstrings ([#6016](https://github.com/aws-powertools/powertools-lambda-python/issues/6016))
+* **api:** migrating the event source data classes utility to mkdocstrings ([#6015](https://github.com/aws-powertools/powertools-lambda-python/issues/6015))
+* **api:** migrating the data masking utility to mkdocstrings ([#6013](https://github.com/aws-powertools/powertools-lambda-python/issues/6013))
+* **api:** migrating the AppConfig utility to mkdocstrings ([#6008](https://github.com/aws-powertools/powertools-lambda-python/issues/6008))
+* **api:** migrating the idempotency utility to mkdocstrings ([#6007](https://github.com/aws-powertools/powertools-lambda-python/issues/6007))
+* **api:** migrating the jmespath utility to mkdocstrings ([#6006](https://github.com/aws-powertools/powertools-lambda-python/issues/6006))
+* **api:** migrating the parameters utility to mkdocstrings ([#6005](https://github.com/aws-powertools/powertools-lambda-python/issues/6005))
+* **api:** migrating the parser utility to mkdocstrings ([#6004](https://github.com/aws-powertools/powertools-lambda-python/issues/6004))
+* **api:** migrating the streaming utility to mkdocstrings ([#6003](https://github.com/aws-powertools/powertools-lambda-python/issues/6003))
+* **api:** migrating the typing utility to mkdocstrings ([#5996](https://github.com/aws-powertools/powertools-lambda-python/issues/5996))
+* **api:** migrating the validation utility to mkdocstrings ([#5972](https://github.com/aws-powertools/powertools-lambda-python/issues/5972))
+* **layer:** update layer version number - v3.5.0 ([#5952](https://github.com/aws-powertools/powertools-lambda-python/issues/5952))
+
+## Features
+
+* **data-masking:** add custom mask functionalities ([#5837](https://github.com/aws-powertools/powertools-lambda-python/issues/5837))
+* **event_source:** add class APIGatewayAuthorizerResponseWebSocket ([#6058](https://github.com/aws-powertools/powertools-lambda-python/issues/6058))
+* **logger:** add clear_state method ([#5956](https://github.com/aws-powertools/powertools-lambda-python/issues/5956))
+* **metrics:** disable metrics flush via environment variables ([#6046](https://github.com/aws-powertools/powertools-lambda-python/issues/6046))
+* **openapi:** enhance support for tuple return type validation ([#5997](https://github.com/aws-powertools/powertools-lambda-python/issues/5997))
+
+## Maintenance
+
+* version bump
+* **ci:** new pre-release 3.5.1a9 ([#6069](https://github.com/aws-powertools/powertools-lambda-python/issues/6069))
+* **ci:** new pre-release 3.5.1a0 ([#5945](https://github.com/aws-powertools/powertools-lambda-python/issues/5945))
+* **ci:** new pre-release 3.5.1a1 ([#5954](https://github.com/aws-powertools/powertools-lambda-python/issues/5954))
+* **ci:** new pre-release 3.5.1a8 ([#6061](https://github.com/aws-powertools/powertools-lambda-python/issues/6061))
+* **ci:** install & configure mkdocstrings plugin ([#5959](https://github.com/aws-powertools/powertools-lambda-python/issues/5959))
+* **ci:** new pre-release 3.5.1a2 ([#5970](https://github.com/aws-powertools/powertools-lambda-python/issues/5970))
+* **ci:** new pre-release 3.5.1a3 ([#5998](https://github.com/aws-powertools/powertools-lambda-python/issues/5998))
+* **ci:** new pre-release 3.5.1a7 ([#6044](https://github.com/aws-powertools/powertools-lambda-python/issues/6044))
+* **ci:** new pre-release 3.5.1a4 ([#6018](https://github.com/aws-powertools/powertools-lambda-python/issues/6018))
+* **ci:** remove pdoc3 library ([#6024](https://github.com/aws-powertools/powertools-lambda-python/issues/6024))
+* **ci:** new pre-release 3.5.1a5 ([#6026](https://github.com/aws-powertools/powertools-lambda-python/issues/6026))
+* **ci:** add new script to bump Lambda layer version ([#6001](https://github.com/aws-powertools/powertools-lambda-python/issues/6001))
+* **ci:** new pre-release 3.5.1a6 ([#6033](https://github.com/aws-powertools/powertools-lambda-python/issues/6033))
+* **deps:** bump squidfunk/mkdocs-material from `471695f` to `7e841df` in /docs ([#6012](https://github.com/aws-powertools/powertools-lambda-python/issues/6012))
+* **deps:** bump zgosalvez/github-actions-ensure-sha-pinned-actions from 3.0.20 to 3.0.21 ([#6064](https://github.com/aws-powertools/powertools-lambda-python/issues/6064))
+* **deps:** bump actions/setup-python from 5.3.0 to 5.4.0 ([#5960](https://github.com/aws-powertools/powertools-lambda-python/issues/5960))
+* **deps:** bump docker/setup-qemu-action from 3.2.0 to 3.3.0 ([#5961](https://github.com/aws-powertools/powertools-lambda-python/issues/5961))
+* **deps:** bump codecov/codecov-action from 5.1.2 to 5.3.1 ([#5964](https://github.com/aws-powertools/powertools-lambda-python/issues/5964))
+* **deps:** bump squidfunk/mkdocs-material from `7e841df` to `c62453b` in /docs ([#6052](https://github.com/aws-powertools/powertools-lambda-python/issues/6052))
+* **deps:** bump actions/setup-node from 4.1.0 to 4.2.0 ([#5963](https://github.com/aws-powertools/powertools-lambda-python/issues/5963))
+* **deps:** bump actions/upload-artifact from 4.5.0 to 4.6.0 ([#5962](https://github.com/aws-powertools/powertools-lambda-python/issues/5962))
+* **deps:** bump release-drafter/release-drafter from 6.0.0 to 6.1.0 ([#5976](https://github.com/aws-powertools/powertools-lambda-python/issues/5976))
+* **deps:** bump zgosalvez/github-actions-ensure-sha-pinned-actions from 3.0.18 to 3.0.20 ([#5977](https://github.com/aws-powertools/powertools-lambda-python/issues/5977))
+* **deps:** bump pypa/gh-action-pypi-publish from 1.12.3 to 1.12.4 ([#5980](https://github.com/aws-powertools/powertools-lambda-python/issues/5980))
+* **deps:** bump docker/setup-buildx-action from 3.8.0 to 3.9.0 ([#6042](https://github.com/aws-powertools/powertools-lambda-python/issues/6042))
+* **deps:** bump docker/setup-qemu-action from 3.3.0 to 3.4.0 ([#6043](https://github.com/aws-powertools/powertools-lambda-python/issues/6043))
+* **deps:** bump aws-actions/configure-aws-credentials from 4.0.2 to 4.0.3 ([#5975](https://github.com/aws-powertools/powertools-lambda-python/issues/5975))
+* **deps:** bump squidfunk/mkdocs-material from `41942f7` to `471695f` in /docs ([#5979](https://github.com/aws-powertools/powertools-lambda-python/issues/5979))
+* **deps:** bump actions/setup-go from 5.2.0 to 5.3.0 ([#5978](https://github.com/aws-powertools/powertools-lambda-python/issues/5978))
+* **deps-dev:** bump aws-cdk from 2.178.0 to 2.178.1 ([#6053](https://github.com/aws-powertools/powertools-lambda-python/issues/6053))
+* **deps-dev:** bump mkdocstrings-python from 1.13.0 to 1.14.2 ([#6011](https://github.com/aws-powertools/powertools-lambda-python/issues/6011))
+* **deps-dev:** bump mkdocs-material from 9.6.1 to 9.6.2 ([#6009](https://github.com/aws-powertools/powertools-lambda-python/issues/6009))
+* **deps-dev:** bump aws-cdk-lib from 2.178.0 to 2.178.1 ([#6047](https://github.com/aws-powertools/powertools-lambda-python/issues/6047))
+* **deps-dev:** bump aws-cdk-aws-lambda-python-alpha from 2.178.0a0 to 2.178.1a0 ([#6048](https://github.com/aws-powertools/powertools-lambda-python/issues/6048))
+* **deps-dev:** bump boto3-stubs from 1.36.14 to 1.36.15 ([#6049](https://github.com/aws-powertools/powertools-lambda-python/issues/6049))
+* **deps-dev:** bump boto3-stubs from 1.36.10 to 1.36.11 ([#6010](https://github.com/aws-powertools/powertools-lambda-python/issues/6010))
+* **deps-dev:** bump boto3-stubs from 1.36.10 to 1.36.12 ([#6014](https://github.com/aws-powertools/powertools-lambda-python/issues/6014))
+* **deps-dev:** bump ruff from 0.9.5 to 0.9.6 ([#6066](https://github.com/aws-powertools/powertools-lambda-python/issues/6066))
+* **deps-dev:** bump mkdocstrings-python from 1.14.2 to 1.14.4 ([#6025](https://github.com/aws-powertools/powertools-lambda-python/issues/6025))
+* **deps-dev:** bump aws-cdk-aws-lambda-python-alpha from 2.177.0a0 to 2.178.0a0 ([#6041](https://github.com/aws-powertools/powertools-lambda-python/issues/6041))
+* **deps-dev:** bump mkdocs-material from 9.5.50 to 9.6.1 ([#5966](https://github.com/aws-powertools/powertools-lambda-python/issues/5966))
+* **deps-dev:** bump black from 24.10.0 to 25.1.0 ([#5968](https://github.com/aws-powertools/powertools-lambda-python/issues/5968))
+* **deps-dev:** bump ruff from 0.9.3 to 0.9.4 ([#5969](https://github.com/aws-powertools/powertools-lambda-python/issues/5969))
+* **deps-dev:** bump cdklabs-generative-ai-cdk-constructs from 0.1.291 to 0.1.292 ([#6051](https://github.com/aws-powertools/powertools-lambda-python/issues/6051))
+* **deps-dev:** bump cfn-lint from 1.22.7 to 1.23.1 ([#5967](https://github.com/aws-powertools/powertools-lambda-python/issues/5967))
+* **deps-dev:** bump mkdocstrings-python from 1.14.5 to 1.14.6 ([#6050](https://github.com/aws-powertools/powertools-lambda-python/issues/6050))
+* **deps-dev:** bump isort from 5.13.2 to 6.0.0 ([#5965](https://github.com/aws-powertools/powertools-lambda-python/issues/5965))
+* **deps-dev:** bump ruff from 0.9.4 to 0.9.5 ([#6039](https://github.com/aws-powertools/powertools-lambda-python/issues/6039))
+* **deps-dev:** bump aws-cdk-lib from 2.177.0 to 2.178.0 ([#6038](https://github.com/aws-powertools/powertools-lambda-python/issues/6038))
+* **deps-dev:** bump mypy from 1.14.1 to 1.15.0 ([#6028](https://github.com/aws-powertools/powertools-lambda-python/issues/6028))
+* **deps-dev:** bump mkdocstrings-python from 1.14.4 to 1.14.5 ([#6032](https://github.com/aws-powertools/powertools-lambda-python/issues/6032))
+* **deps-dev:** bump cfn-lint from 1.23.1 to 1.24.0 ([#6030](https://github.com/aws-powertools/powertools-lambda-python/issues/6030))
+* **deps-dev:** bump boto3-stubs from 1.36.14 to 1.36.16 ([#6057](https://github.com/aws-powertools/powertools-lambda-python/issues/6057))
+* **deps-dev:** bump cdklabs-generative-ai-cdk-constructs from 0.1.290 to 0.1.291 ([#6031](https://github.com/aws-powertools/powertools-lambda-python/issues/6031))
+* **deps-dev:** bump boto3-stubs from 1.36.12 to 1.36.14 ([#6029](https://github.com/aws-powertools/powertools-lambda-python/issues/6029))
+* **deps-dev:** bump mkdocs-material from 9.6.2 to 9.6.3 ([#6065](https://github.com/aws-powertools/powertools-lambda-python/issues/6065))
+* **deps-dev:** bump coverage from 7.6.10 to 7.6.11 ([#6067](https://github.com/aws-powertools/powertools-lambda-python/issues/6067))
+* **deps-dev:** bump aws-cdk from 2.177.0 to 2.178.0 ([#6040](https://github.com/aws-powertools/powertools-lambda-python/issues/6040))
+* **docs:** enable privacy plugin in docs ([#6036](https://github.com/aws-powertools/powertools-lambda-python/issues/6036))
+
+
 <a name="v3.5.0"></a>
 ## [v3.5.0] - 2025-01-28
 ## Bug Fixes

aws_lambda_powertools/event_handler/async_execution/exceptions.py

@@ -0,0 +1,2 @@
+class RouteNotFoundError(Exception):
+    pass

aws_lambda_powertools/event_handler/async_execution/router.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from .routes.aws_config_rule import AwsConfigRuleRoute
+from .routes.cloud_watch_alarm import CloudWatchAlarmRoute
+from .routes.cloud_watch_logs import CloudWatchLogsRoute
+from .routes.code_deploy_lifecycle_hook import CodeDeployLifecycleHookRoute
+from .routes.event_bridge import EventBridgeRoute
+from .routes.s3 import S3Route
+from .routes.secrets_manager import SecretsManagerRoute
+from .routes.ses import SESRoute
+from .routes.sns import SNSRoute
+
+if TYPE_CHECKING:
+    from .routes.base import BaseRoute
+
+
+class Router:
+    _routes: list[BaseRoute]
+
+    def __init__(self):
+        self._routes = []
+
+    def aws_config_rule(
+        self,
+        arn: str | None = None,
+        rule_name: str | None = None,
+        rule_name_prefix: str | None = None,
+        rule_id: str | None = None,
+    ) -> Callable:
+        def wrapper_aws_config_rule(func: Callable):
+            self._routes.append(
+                AwsConfigRuleRoute(
+                    func=func,
+                    arn=arn,
+                    rule_name=rule_name,
+                    rule_name_prefix=rule_name_prefix,
+                    rule_id=rule_id,
+                ),
+            )
+
+        return wrapper_aws_config_rule
+
+    def cloud_watch_alarm(
+        self,
+        arn: str | None = None,
+        alarm_name: str | None = None,
+        alarm_name_prefix: str | None = None,
+    ) -> Callable:
+        def wrapper_cloud_watch_alarm(func: Callable):
+            self._routes.append(
+                CloudWatchAlarmRoute(func=func, arn=arn, alarm_name=alarm_name, alarm_name_prefix=alarm_name_prefix),
+            )
+
+        return wrapper_cloud_watch_alarm
+
+    def cloud_watch_logs(
+        self,
+        log_group: str | None = None,
+        log_group_prefix: str | None = None,
+        log_stream: str | None = None,
+        log_stream_prefix: str | None = None,
+        subscription_filters: str | list[str] | None = None,
+    ) -> Callable:
+        def wrapper_cloud_watch_logs(func: Callable):
+            self._routes.append(
+                CloudWatchLogsRoute(
+                    func=func,
+                    log_group=log_group,
+                    log_group_prefix=log_group_prefix,
+                    log_stream=log_stream,
+                    log_stream_prefix=log_stream_prefix,
+                    subscription_filters=subscription_filters,
+                ),
+            )
+
+        return wrapper_cloud_watch_logs
+
+    def code_deploy_lifecycle_hook(self) -> Callable:
+        def wrapper_code_deploy_lifecycle_hook(func: Callable):
+            self._routes.append(CodeDeployLifecycleHookRoute(func=func))
+
+        return wrapper_code_deploy_lifecycle_hook
+
+    def event_bridge(
+        self,
+        detail_type: str | None = None,
+        source: str | None = None,
+        resources: str | list[str] | None = None,
+    ) -> Callable:
+        def wrap_event_bridge(func: Callable):
+            self._routes.append(
+                EventBridgeRoute(func=func, detail_type=detail_type, source=source, resources=resources),
+            )
+
+        return wrap_event_bridge
+
+    def s3(
+        self,
+        bucket: str | None = None,
+        bucket_prefix: str | None = None,
+        key: str | None = None,
+        key_prefix: str | None = None,
+        key_suffix: str | None = None,
+        event_name: str | None = None,
+    ) -> Callable:
+        def wrap_s3(func: Callable):
+            self._routes.append(
+                S3Route(
+                    func=func,
+                    bucket=bucket,
+                    bucket_prefix=bucket_prefix,
+                    key=key,
+                    key_prefix=key_prefix,
+                    key_suffix=key_suffix,
+                    event_name=event_name,
+                ),
+            )
+
+        return wrap_s3
+
+    def secrets_manager(self, secret_id: str | None = None, secret_name_prefix: str | None = None):
+        def wrap_secrets_manager(func: Callable):
+            self._routes.append(
+                SecretsManagerRoute(func=func, secret_id=secret_id, secret_name_prefix=secret_name_prefix),
+            )
+
+        return wrap_secrets_manager
+
+    def ses(
+        self,
+        mail_to: str | list[str] | None = None,
+        mail_from: str | list[str] | None = None,
+        mail_subject: str | None = None,
+    ) -> Callable:
+        def wrap_ses(func: Callable):
+            self._routes.append(SESRoute(func=func, mail_to=mail_to, mail_from=mail_from, mail_subject=mail_subject))
+
+        return wrap_ses
+
+    def sns(
+        self,
+        arn: str | None = None,
+        name: str | None = None,
+        name_prefix: str | None = None,
+        subject: str | None = None,
+        subject_prefix: str | None = None,
+    ) -> Callable:
+        def wrap_sns(func: Callable):
+            self._routes.append(
+                SNSRoute(
+                    func=func,
+                    arn=arn,
+                    name=name,
+                    name_prefix=name_prefix,
+                    subject=subject,
+                    subject_prefix=subject_prefix,
+                ),
+            )
+
+        return wrap_sns
+
+    def resolve_route(self, event: dict[str, Any]) -> tuple[Callable, Any] | None:
+        for route in self._routes:
+            data = route.match(event=event)
+            if data is not None:
+                return data
+        return None