feat(nested-event-sources): Generic unwrapping of event source data

aws_lambda_powertools/utilities/data_classes/cloud_watch_logs_event.py

@@ -2,10 +2,10 @@
 import zlib
 from typing import Dict, List, Optional
 
-from aws_lambda_powertools.utilities.data_classes.common import DictWrapper
+from aws_lambda_powertools.utilities.data_classes.common import DictWrapper, EventWrapper
 
 
-class CloudWatchLogsLogEvent(DictWrapper):
+class CloudWatchLogsLogEvent(EventWrapper):
     @property
     def get_id(self) -> str:
         """The ID property is a unique identifier for every log event."""
@@ -72,7 +72,7 @@ def log_events(self) -> List[CloudWatchLogsLogEvent]:
         return [CloudWatchLogsLogEvent(i) for i in self["logEvents"]]
 
 
-class CloudWatchLogsEvent(DictWrapper):
+class CloudWatchLogsEvent(EventWrapper):
     """CloudWatch Logs log stream event
 
     You can use a Lambda function to monitor and analyze logs from an Amazon CloudWatch Logs log stream.

aws_lambda_powertools/utilities/data_classes/common.py

@@ -2,7 +2,7 @@
 import json
 from collections.abc import Mapping
 from functools import cached_property
-from typing import Any, Callable, Dict, Iterator, List, Optional, overload
+from typing import Any, Callable, Dict, Iterator, List, Optional, Type, TypeVar, overload
 
 from aws_lambda_powertools.shared.headers_serializer import BaseHeadersSerializer
 from aws_lambda_powertools.utilities.data_classes.shared_functions import (
@@ -95,6 +95,52 @@ def raw_event(self) -> Dict[str, Any]:
         return self._data
 
 
+class EventWrapper(DictWrapper):
+    NestedEvent = TypeVar("NestedEvent", bound=DictWrapper)
+
+    def __init__(self, data: Dict[str, Any], json_deserializer: Optional[Callable] = None):
+        """
+        Parameters
+        ----------
+        data : Dict[str, Any]
+            Lambda Event Source Event payload
+        json_deserializer : Callable, optional
+            function to deserialize `str`, `bytes`, `bytearray`
+            containing a JSON document to a Python `obj`,
+            by default json.loads
+        """
+        super().__init__(data, json_deserializer)
+
+    def nested_event_contents(self):
+        records = self.get("Records")
+        if records is None:
+            raise KeyError("No 'Records' key found in the event data.")
+        for record in records:
+            if not isinstance(record, dict):
+                raise TypeError(f"Expected 'Records' to be a dictionary, but got {type(record)}.")
+            body = record.get("body")
+            if body is not None:
+                yield body
+            else:
+                raise KeyError("No 'body' key found in the 'Records' dict.")
+
+    def decode_nested_events(self, nested_event_class: Type[NestedEvent], nested_event_content_deserializer=None):
+        if nested_event_content_deserializer is None:
+            nested_event_content_deserializer = self._json_deserializer
+
+        for content in self.nested_event_contents():
+            deserialized_data = nested_event_content_deserializer(content)
+            yield nested_event_class(deserialized_data)
+
+    def decode_nested_event(self, nested_event_class: Type[NestedEvent], nested_event_content_deserializer=None):
+        if nested_event_content_deserializer is None:
+            nested_event_content_deserializer = self._json_deserializer
+
+        for content in self.nested_event_contents():
+            deserialized_data = nested_event_content_deserializer(content)
+            return nested_event_class(deserialized_data)
+
+
 class BaseProxyEvent(DictWrapper):
     @property
     def headers(self) -> Dict[str, str]:
@@ -173,10 +219,12 @@ def http_method(self) -> str:
         return self["httpMethod"]
 
     @overload
-    def get_query_string_value(self, name: str, default_value: str) -> str: ...
+    def get_query_string_value(self, name: str, default_value: str) -> str:
+        ...
 
     @overload
-    def get_query_string_value(self, name: str, default_value: Optional[str] = None) -> Optional[str]: ...
+    def get_query_string_value(self, name: str, default_value: Optional[str] = None) -> Optional[str]:
+        ...
 
     def get_query_string_value(self, name: str, default_value: Optional[str] = None) -> Optional[str]:
         """Get query string value by name
@@ -229,15 +277,17 @@ def get_header_value(
         name: str,
         default_value: str,
         case_sensitive: bool = False,
-    ) -> str: ...
+    ) -> str:
+        ...
 
     @overload
     def get_header_value(
         self,
         name: str,
         default_value: Optional[str] = None,
         case_sensitive: bool = False,
-    ) -> Optional[str]: ...
+    ) -> Optional[str]:
+        ...
 
     def get_header_value(
         self,

aws_lambda_powertools/utilities/data_classes/event_bridge_event.py

@@ -1,9 +1,10 @@
+import json
 from typing import Any, Dict, List, Optional
 
-from aws_lambda_powertools.utilities.data_classes.common import DictWrapper
+from aws_lambda_powertools.utilities.data_classes.common import EventWrapper
 
 
-class EventBridgeEvent(DictWrapper):
+class EventBridgeEvent(EventWrapper):
     """Amazon EventBridge Event
 
     Documentation:
@@ -67,3 +68,6 @@ def detail(self) -> Dict[str, Any]:
     def replay_name(self) -> Optional[str]:
         """Identifies whether the event is being replayed and what is the name of the replay."""
         return self["replay-name"]
+
+    def nested_event_contents(self):
+        yield json.dumps(self.get("detail"))

aws_lambda_powertools/utilities/data_classes/kafka_event.py

@@ -75,15 +75,17 @@ def get_header_value(
         name: str,
         default_value: str,
         case_sensitive: bool = True,
-    ) -> str: ...
+    ) -> str:
+        ...
 
     @overload
     def get_header_value(
         self,
         name: str,
         default_value: Optional[str] = None,
         case_sensitive: bool = True,
-    ) -> Optional[str]: ...
+    ) -> Optional[str]:
+        ...
 
     def get_header_value(
         self,

aws_lambda_powertools/utilities/data_classes/kinesis_firehose_event.py

@@ -7,7 +7,7 @@
 
 from typing_extensions import Literal
 
-from aws_lambda_powertools.utilities.data_classes.common import DictWrapper
+from aws_lambda_powertools.utilities.data_classes.common import DictWrapper, EventWrapper
 
 
 @dataclass(repr=False, order=False, frozen=True)
@@ -208,7 +208,7 @@ def subsequence_number(self) -> int:
         return self._metadata["subsequenceNumber"]
 
 
-class KinesisFirehoseRecord(DictWrapper):
+class KinesisFirehoseRecord(EventWrapper):
     @property
     def approximate_arrival_timestamp(self) -> int:
         """The approximate time that the record was inserted into the delivery stream"""
@@ -271,7 +271,7 @@ def build_data_transformation_response(
         )
 
 
-class KinesisFirehoseEvent(DictWrapper):
+class KinesisFirehoseEvent(EventWrapper):
     """Kinesis Data Firehose event
 
     Documentation:
@@ -303,3 +303,9 @@ def region(self) -> str:
     def records(self) -> Iterator[KinesisFirehoseRecord]:
         for record in self["records"]:
             yield KinesisFirehoseRecord(data=record, json_deserializer=self._json_deserializer)
+
+    def nested_event_contents(self):
+        for record in self.get("records"):
+            body = record.get("data")
+            body = base64.b64decode(body).decode("utf-8")
+            yield body

aws_lambda_powertools/utilities/data_classes/kinesis_stream_event.py

@@ -6,7 +6,7 @@
 from aws_lambda_powertools.utilities.data_classes.cloud_watch_logs_event import (
     CloudWatchLogsDecodedData,
 )
-from aws_lambda_powertools.utilities.data_classes.common import DictWrapper
+from aws_lambda_powertools.utilities.data_classes.common import DictWrapper, EventWrapper
 
 
 class KinesisStreamRecordPayload(DictWrapper):
@@ -95,7 +95,7 @@ def kinesis(self) -> KinesisStreamRecordPayload:
         return KinesisStreamRecordPayload(self._data)
 
 
-class KinesisStreamEvent(DictWrapper):
+class KinesisStreamEvent(EventWrapper):
     """Kinesis stream event
 
     Documentation: