Merging from develop

Author: leandrodamascena

.clusterfuzzlite/Dockerfile

@@ -0,0 +1,12 @@
+FROM gcr.io/oss-fuzz-base/base-builder-python
+
+# Copy project source
+COPY . $SRC/powertools
+
+WORKDIR $SRC/powertools
+
+# Install project dependencies
+RUN pip3 install -e ".[all]"
+
+# Copy build script
+COPY .clusterfuzzlite/build.sh $SRC/

.clusterfuzzlite/build.sh

@@ -0,0 +1,6 @@
+#!/bin/bash -eu
+
+# Build fuzz targets from tests/fuzz/
+for fuzzer in $(find $SRC/powertools/tests/fuzz -name 'fuzz_*.py'); do
+    compile_python_fuzzer "$fuzzer"
+done

.clusterfuzzlite/project.yaml

@@ -0,0 +1,4 @@
+language: python
+main_repo: https://github.com/aws-powertools/powertools-lambda-python
+sanitizers:
+  - address

.github/workflows/cflite_scheduled.yml

@@ -0,0 +1,34 @@
+name: ClusterFuzzLite fuzzing
+
+on:
+  schedule:
+    # Run daily at 8 AM UTC
+    - cron: "0 8 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  PR:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+    steps:
+      - name: Build Fuzzers
+        id: build
+        uses: google/clusterfuzzlite/actions/build_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          language: python
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          sanitizer: address
+
+      - name: Run Fuzzers
+        id: run
+        uses: google/clusterfuzzlite/actions/run_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          fuzz-seconds: 30
+          mode: code-change
+          sanitizer: address

aws_lambda_powertools/event_handler/api_gateway.py

@@ -826,6 +826,8 @@ def _openapi_operation_request_body(
 
         # Generate the request body media type
         request_media_content: dict[str, Any] = {"schema": body_schema}
+        if field_info.openapi_examples:
+            request_media_content["examples"] = field_info.openapi_examples
         request_body_oai["content"] = {request_media_type: request_media_content}
         return request_body_oai
 
@@ -2459,7 +2461,7 @@ def register_resolver(func: AnyCallableT) -> AnyCallableT:
 
         return register_resolver
 
-    def resolve(self, event: dict[str, Any], context: LambdaContext) -> dict[str, Any]:
+    def resolve(self, event: Mapping[str, Any], context: LambdaContext) -> dict[str, Any]:
         """Resolves the response based on the provide event and decorator routes
 
         ## Internals
@@ -2512,10 +2514,10 @@ def resolve(self, event: dict[str, Any], context: LambdaContext) -> dict[str, An
             event = event.raw_event
 
         if self._debug:
-            print(self._serializer(event))
+            print(self._serializer(cast(dict, event)))
 
         # Populate router(s) dependencies without keeping a reference to each registered router
-        BaseRouter.current_event = self._to_proxy_event(event)
+        BaseRouter.current_event = self._to_proxy_event(cast(dict, event))
         BaseRouter.lambda_context = context
 
         response = self._resolve().build(self.current_event, self._cors)

aws_lambda_powertools/event_handler/openapi/params.py

@@ -724,6 +724,8 @@ def __init__(
         )
         if examples is not None:
             kwargs["examples"] = examples
+        if openapi_examples is not None:
+            kwargs["openapi_examples"] = openapi_examples
         current_json_schema_extra = json_schema_extra or extra
 
         # Pydantic 2.12+ no longer copies alias to validation_alias automatically
@@ -733,6 +735,7 @@ def __init__(
         elif alias is None and validation_alias is not _Unset and validation_alias is not None:
             alias = validation_alias
             kwargs["alias"] = alias
+        self.openapi_examples = openapi_examples
 
         kwargs.update(
             {
@@ -1124,11 +1127,23 @@ def get_field_info_annotated_type(annotation, value, is_path_param: bool) -> tup
     """
     annotated_args = get_args(annotation)
     type_annotation = annotated_args[0]
-    powertools_annotations = [arg for arg in annotated_args[1:] if isinstance(arg, FieldInfo)]
+
+    # Handle both FieldInfo instances and FieldInfo subclasses (e.g., Body vs Body())
+    powertools_annotations: list[FieldInfo] = []
+    for arg in annotated_args[1:]:
+        if isinstance(arg, FieldInfo):
+            powertools_annotations.append(arg)
+        elif isinstance(arg, type) and issubclass(arg, FieldInfo):
+            # If it's a class (e.g., Body instead of Body()), instantiate it
+            powertools_annotations.append(arg())
 
     # Preserve non-FieldInfo metadata (like annotated_types constraints)
     # This is important for constraints like Interval, Gt, Lt, etc.
-    other_metadata = [arg for arg in annotated_args[1:] if not isinstance(arg, FieldInfo)]
+    other_metadata = [
+        arg
+        for arg in annotated_args[1:]
+        if not isinstance(arg, FieldInfo) and not (isinstance(arg, type) and issubclass(arg, FieldInfo))
+    ]
 
     # Determine which annotation to use
     powertools_annotation: FieldInfo | None = None

aws_lambda_powertools/logging/formatter.py

@@ -281,6 +281,12 @@ def append_context_keys(self, **additional_keys: Any) -> Generator[None, None, N
         **additional_keys: Any
             Key-value pairs to include in the log context during the lifespan of the context manager.
 
+        Warning
+        -------
+        All keys added within this context are removed when exiting, even if they existed before.
+        If a key with the same name already exists, the original value will be lost after the context exits.
+        To persist keys across multiple log messages, use `append_keys()` instead.
+
         Example
         --------
             logger = Logger(service="example_service")

aws_lambda_powertools/logging/logger.py

@@ -820,6 +820,12 @@ def append_context_keys(self, **additional_keys: Any) -> Generator[None, None, N
         **additional_keys: Any
             Key-value pairs to include in the log context during the lifespan of the context manager.
 
+        Warning
+        -------
+        All keys added within this context are removed when exiting, even if they existed before.
+        If a key with the same name already exists, the original value will be lost after the context exits.
+        To persist keys across multiple log messages, use `append_keys()` instead.
+
         Example
         --------
         **Logging with contextual keys**

aws_lambda_powertools/metrics/metrics.py

@@ -123,6 +123,13 @@ def add_metric(
     def add_dimension(self, name: str, value: str) -> None:
         self.provider.add_dimension(name=name, value=value)
 
+    def add_dimensions(self, **dimensions: str) -> None:
+        """Add a new set of dimensions creating an additional dimension array.
+
+        Creates a new dimension set in the CloudWatch EMF Dimensions array.
+        """
+        self.provider.add_dimensions(**dimensions)
+
     def serialize_metric_set(
         self,
         metrics: dict | None = None,

aws_lambda_powertools/metrics/provider/cloudwatch_emf/cloudwatch.py

@@ -94,6 +94,7 @@ def __init__(
 
         self.metadata_set = metadata_set if metadata_set is not None else {}
         self.timestamp: int | None = None
+        self.dimension_sets: list[dict[str, str]] = []  # Store multiple dimension sets
 
         self._metric_units = [unit.value for unit in MetricUnit]
         self._metric_unit_valid_options = list(MetricUnit.__members__)
@@ -256,21 +257,30 @@ def serialize_metric_set(
 
             metric_names_and_values.update({metric_name: metric_value})
 
+        # Build Dimensions array: primary set + additional dimension sets
+        dimension_arrays: list[list[str]] = [list(dimensions.keys())]
+        all_dimensions: dict[str, str] = dict(dimensions)
+
+        # Add each additional dimension set
+        for dim_set in self.dimension_sets:
+            all_dimensions.update(dim_set)
+            dimension_arrays.append(list(dim_set.keys()))
+
         return {
             "_aws": {
                 "Timestamp": self.timestamp or int(datetime.datetime.now().timestamp() * 1000),  # epoch
                 "CloudWatchMetrics": [
                     {
                         "Namespace": self.namespace,  # "test_namespace"
-                        "Dimensions": [list(dimensions.keys())],  # [ "service" ]
+                        "Dimensions": dimension_arrays,  # [["service"], ["env", "region"]]
                         "Metrics": metric_definition,
                     },
                 ],
             },
             # NOTE: Mypy doesn't recognize splats '** syntax' in TypedDict
-            **dimensions,  # "service": "test_service"
-            **metadata,  # type: ignore[typeddict-item] # "username": "test"
-            **metric_names_and_values,  # "single_metric": 1.0
+            **all_dimensions,  # type: ignore[typeddict-item]  # All dimension key-value pairs
+            **metadata,  # type: ignore[typeddict-item]
+            **metric_names_and_values,
         }
 
     def add_dimension(self, name: str, value: str) -> None:
@@ -316,6 +326,70 @@ def add_dimension(self, name: str, value: str) -> None:
 
         self.dimension_set[name] = value
 
+    def add_dimensions(self, **dimensions: str) -> None:
+        """Add a new set of dimensions creating an additional dimension array.
+
+        Creates a new dimension set in the CloudWatch EMF Dimensions array.
+
+        Example
+        -------
+        **Add multiple dimension sets**
+
+            metrics.add_dimensions(environment="prod", region="us-east-1")
+
+        Parameters
+        ----------
+        dimensions : str
+            Dimension key-value pairs as keyword arguments
+        """
+        logger.debug(f"Adding dimension set: {dimensions}")
+
+        if not dimensions:
+            warnings.warn(
+                "Empty dimensions dictionary provided",
+                category=PowertoolsUserWarning,
+                stacklevel=2,
+            )
+            return
+
+        sanitized = self._sanitize_dimensions(dimensions)
+        if not sanitized:
+            return
+
+        self._validate_dimension_limit(sanitized)
+
+        self.dimension_sets.append({**self.default_dimensions, **sanitized})
+
+    def _sanitize_dimensions(self, dimensions: dict[str, str]) -> dict[str, str]:
+        """Convert dimension values to strings and filter out empty ones."""
+        sanitized: dict[str, str] = {}
+
+        for name, value in dimensions.items():
+            str_name = str(name)
+            str_value = str(value)
+
+            if not str_name.strip() or not str_value.strip():
+                warnings.warn(
+                    f"Dimension {str_name} has empty name or value",
+                    category=PowertoolsUserWarning,
+                    stacklevel=2,
+                )
+                continue
+
+            sanitized[str_name] = str_value
+
+        return sanitized
+
+    def _validate_dimension_limit(self, new_dimensions: dict[str, str]) -> None:
+        """Validate that adding new dimensions won't exceed CloudWatch limits."""
+        all_keys = set(self.dimension_set.keys())
+        for ds in self.dimension_sets:
+            all_keys.update(ds.keys())
+        all_keys.update(new_dimensions.keys())
+
+        if len(all_keys) > MAX_DIMENSIONS:
+            raise SchemaValidationError(f"Maximum dimensions ({MAX_DIMENSIONS}) exceeded")
+
     def add_metadata(self, key: str, value: Any) -> None:
         """Adds high cardinal metadata for metrics object
 
@@ -377,6 +451,7 @@ def clear_metrics(self) -> None:
         logger.debug("Clearing out existing metric set from memory")
         self.metric_set.clear()
         self.dimension_set.clear()
+        self.dimension_sets.clear()
         self.metadata_set.clear()
         self.set_default_dimensions(**self.default_dimensions)