Merge remote-tracking branch 'origin/develop' into tonnico/feat/support-pydantic

Author: tonnico

.github/workflows/dependency-review.yml

@@ -22,4 +22,4 @@ jobs:
       - name: 'Checkout Repository'
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       - name: 'Dependency Review'
-        uses: actions/dependency-review-action@595b5aeba73380359d98a5e087f648dbb0edce1b # v4.7.3
+        uses: actions/dependency-review-action@56339e523c0409420f6c2c9a2f4292bbb3c07dd3 # v4.8.0

CHANGELOG.md

@@ -14,8 +14,10 @@
 
 ## Documentation
 
+* **event_handler:** remove the wrong CORS warning ([#7385](https://github.com/aws-powertools/powertools-lambda-python/issues/7385))
 * **event_handler:** update test section ([#7374](https://github.com/aws-powertools/powertools-lambda-python/issues/7374))
 * **event_handler:** add info section about types ([#7368](https://github.com/aws-powertools/powertools-lambda-python/issues/7368))
+* **logger:** clarify Advanced Logging Controls interaction with sampling ([#7429](https://github.com/aws-powertools/powertools-lambda-python/issues/7429))
 
 ## Features
 
@@ -25,19 +27,49 @@
 
 ## Maintenance
 
-* **ci:** new pre-release 3.20.1a1 ([#7372](https://github.com/aws-powertools/powertools-lambda-python/issues/7372))
+* **ci:** new pre-release 3.20.1a2 ([#7383](https://github.com/aws-powertools/powertools-lambda-python/issues/7383))
 * **ci:** new pre-release 3.20.1a0 ([#7362](https://github.com/aws-powertools/powertools-lambda-python/issues/7362))
+* **ci:** new pre-release 3.20.1a6 ([#7442](https://github.com/aws-powertools/powertools-lambda-python/issues/7442))
+* **ci:** new pre-release 3.20.1a1 ([#7372](https://github.com/aws-powertools/powertools-lambda-python/issues/7372))
+* **ci:** new pre-release 3.20.1a3 ([#7393](https://github.com/aws-powertools/powertools-lambda-python/issues/7393))
+* **ci:** new pre-release 3.20.1a4 ([#7404](https://github.com/aws-powertools/powertools-lambda-python/issues/7404))
+* **ci:** new pre-release 3.20.1a5 ([#7418](https://github.com/aws-powertools/powertools-lambda-python/issues/7418))
+* **deps:** bump mkdocs-material from 9.6.19 to 9.6.20 in /docs ([#7387](https://github.com/aws-powertools/powertools-lambda-python/issues/7387))
+* **deps:** bump pydantic-settings from 2.10.1 to 2.11.0 ([#7434](https://github.com/aws-powertools/powertools-lambda-python/issues/7434))
 * **deps:** bump mkdocs-material from 9.6.18 to 9.6.19 ([#7359](https://github.com/aws-powertools/powertools-lambda-python/issues/7359))
+* **deps:** bump valkey-glide from 2.0.1 to 2.1.0 ([#7403](https://github.com/aws-powertools/powertools-lambda-python/issues/7403))
+* **deps:** bump mkdocs-llmstxt from 0.3.1 to 0.3.2 ([#7436](https://github.com/aws-powertools/powertools-lambda-python/issues/7436))
+* **deps:** bump actions/dependency-review-action from 4.7.3 to 4.8.0 ([#7432](https://github.com/aws-powertools/powertools-lambda-python/issues/7432))
 * **deps:** bump protobuf from 6.32.0 to 6.32.1 ([#7376](https://github.com/aws-powertools/powertools-lambda-python/issues/7376))
-* **deps-dev:** bump boto3-stubs from 1.40.27 to 1.40.29 ([#7371](https://github.com/aws-powertools/powertools-lambda-python/issues/7371))
-* **deps-dev:** bump mypy from 1.17.1 to 1.18.1 ([#7375](https://github.com/aws-powertools/powertools-lambda-python/issues/7375))
+* **deps:** bump pydantic from 2.11.7 to 2.11.9 ([#7390](https://github.com/aws-powertools/powertools-lambda-python/issues/7390))
+* **deps:** bump mkdocs-llmstxt from 0.3.1 to 0.3.2 in /docs ([#7409](https://github.com/aws-powertools/powertools-lambda-python/issues/7409))
+* **deps:** bump squidfunk/mkdocs-material from `209b62d` to `86d21da` in /docs ([#7386](https://github.com/aws-powertools/powertools-lambda-python/issues/7386))
+* **deps:** bump mkdocs-material from 9.6.19 to 9.6.20 ([#7389](https://github.com/aws-powertools/powertools-lambda-python/issues/7389))
+* **deps-dev:** bump boto3-stubs from 1.40.30 to 1.40.31 ([#7388](https://github.com/aws-powertools/powertools-lambda-python/issues/7388))
+* **deps-dev:** bump aws-cdk-aws-lambda-python-alpha from 2.214.0a0 to 2.215.0a0 ([#7391](https://github.com/aws-powertools/powertools-lambda-python/issues/7391))
+* **deps-dev:** bump sentry-sdk from 2.38.0 to 2.39.0 ([#7426](https://github.com/aws-powertools/powertools-lambda-python/issues/7426))
+* **deps-dev:** bump aws-cdk-lib from 2.215.0 to 2.217.0 ([#7423](https://github.com/aws-powertools/powertools-lambda-python/issues/7423))
+* **deps-dev:** bump types-protobuf from 6.30.2.20250822 to 6.32.1.20250918 ([#7406](https://github.com/aws-powertools/powertools-lambda-python/issues/7406))
+* **deps-dev:** bump aws-cdk-aws-lambda-python-alpha from 2.215.0a0 to 2.217.0a0 ([#7424](https://github.com/aws-powertools/powertools-lambda-python/issues/7424))
+* **deps-dev:** bump boto3-stubs from 1.40.32 to 1.40.39 ([#7425](https://github.com/aws-powertools/powertools-lambda-python/issues/7425))
+* **deps-dev:** bump coverage from 7.10.6 to 7.10.7 ([#7437](https://github.com/aws-powertools/powertools-lambda-python/issues/7437))
 * **deps-dev:** bump pytest-asyncio from 1.1.0 to 1.2.0 ([#7377](https://github.com/aws-powertools/powertools-lambda-python/issues/7377))
-* **deps-dev:** bump pytest-cov from 6.3.0 to 7.0.0 ([#7357](https://github.com/aws-powertools/powertools-lambda-python/issues/7357))
+* **deps-dev:** bump boto3-stubs from 1.40.31 to 1.40.32 ([#7395](https://github.com/aws-powertools/powertools-lambda-python/issues/7395))
+* **deps-dev:** bump mypy from 1.17.1 to 1.18.1 ([#7375](https://github.com/aws-powertools/powertools-lambda-python/issues/7375))
+* **deps-dev:** bump ruff from 0.12.12 to 0.13.2 ([#7427](https://github.com/aws-powertools/powertools-lambda-python/issues/7427))
+* **deps-dev:** bump sentry-sdk from 2.37.1 to 2.38.0 ([#7402](https://github.com/aws-powertools/powertools-lambda-python/issues/7402))
+* **deps-dev:** bump boto3-stubs from 1.40.27 to 1.40.29 ([#7371](https://github.com/aws-powertools/powertools-lambda-python/issues/7371))
 * **deps-dev:** bump aws-cdk from 2.1029.0 to 2.1029.1 ([#7370](https://github.com/aws-powertools/powertools-lambda-python/issues/7370))
+* **deps-dev:** bump aws-cdk from 2.1029.1 to 2.1029.2 ([#7400](https://github.com/aws-powertools/powertools-lambda-python/issues/7400))
+* **deps-dev:** bump mypy from 1.18.1 to 1.18.2 ([#7435](https://github.com/aws-powertools/powertools-lambda-python/issues/7435))
+* **deps-dev:** bump boto3-stubs from 1.40.39 to 1.40.40 ([#7433](https://github.com/aws-powertools/powertools-lambda-python/issues/7433))
+* **deps-dev:** bump boto3-stubs from 1.40.26 to 1.40.27 ([#7358](https://github.com/aws-powertools/powertools-lambda-python/issues/7358))
+* **deps-dev:** bump pytest-cov from 6.3.0 to 7.0.0 ([#7357](https://github.com/aws-powertools/powertools-lambda-python/issues/7357))
+* **deps-dev:** bump aws-cdk from 2.1029.2 to 2.1029.3 ([#7420](https://github.com/aws-powertools/powertools-lambda-python/issues/7420))
 * **deps-dev:** bump testcontainers from 4.12.0 to 4.13.0 ([#7360](https://github.com/aws-powertools/powertools-lambda-python/issues/7360))
 * **deps-dev:** bump sentry-sdk from 2.37.0 to 2.37.1 ([#7356](https://github.com/aws-powertools/powertools-lambda-python/issues/7356))
+* **deps-dev:** bump pytest-mock from 3.15.0 to 3.15.1 ([#7396](https://github.com/aws-powertools/powertools-lambda-python/issues/7396))
 * **deps-dev:** bump boto3-stubs from 1.40.29 to 1.40.30 ([#7378](https://github.com/aws-powertools/powertools-lambda-python/issues/7378))
-* **deps-dev:** bump boto3-stubs from 1.40.26 to 1.40.27 ([#7358](https://github.com/aws-powertools/powertools-lambda-python/issues/7358))
 
 
 <a name="v3.20.0"></a>

aws_lambda_powertools/event_handler/middlewares/base.py

@@ -19,7 +19,7 @@ def __name__(self) -> str:  # noqa A003
         ...
 
 
-class BaseMiddlewareHandler(Generic[EventHandlerInstance], ABC):
+class BaseMiddlewareHandler(ABC, Generic[EventHandlerInstance]):
     """Base implementation for Middlewares to run code before and after in a chain.
 
 

aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

@@ -3,7 +3,6 @@
 import dataclasses
 import json
 import logging
-from copy import deepcopy
 from typing import TYPE_CHECKING, Any, Callable, Mapping, MutableMapping, Sequence, cast, get_origin
 from urllib.parse import parse_qs
 
@@ -15,6 +14,7 @@
     _normalize_errors,
     _regenerate_error_with_loc,
     get_missing_field_error,
+    is_sequence_field,
     lenient_issubclass,
 )
 from aws_lambda_powertools.event_handler.openapi.dependant import is_scalar_field
@@ -153,11 +153,10 @@ def _parse_form_data(self, app: EventHandlerInstance) -> dict[str, Any]:
         """Parse URL-encoded form data from the request body."""
         try:
             body = app.current_event.decoded_body or ""
-            # parse_qs returns dict[str, list[str]], but we want dict[str, str] for single values
+            # NOTE: Keep values as lists; we'll normalize per-field later based on the expected type.
+            # This avoids breaking List[...] fields when only a single value is provided.
             parsed = parse_qs(body, keep_blank_values=True)
-
-            result: dict[str, Any] = {key: values[0] if len(values) == 1 else values for key, values in parsed.items()}
-            return result
+            return parsed
 
         except Exception as e:  # pragma: no cover
             raise RequestValidationError(  # pragma: no cover
@@ -317,12 +316,12 @@ def _prepare_response_content(
 def _request_params_to_args(
     required_params: Sequence[ModelField],
     received_params: Mapping[str, Any],
-) -> tuple[dict[str, Any], list[Any]]:
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
     """
     Convert the request params to a dictionary of values using validation, and returns a list of errors.
     """
-    values = {}
-    errors = []
+    values: dict[str, Any] = {}
+    errors: list[dict[str, Any]] = []
 
     for field in required_params:
         field_info = field.field_info
@@ -331,16 +330,12 @@ def _request_params_to_args(
         if not isinstance(field_info, Param):
             raise AssertionError(f"Expected Param field_info, got {field_info}")
 
-        value = received_params.get(field.alias)
-
         loc = (field_info.in_.value, field.alias)
+        value = received_params.get(field.alias)
 
         # If we don't have a value, see if it's required or has a default
         if value is None:
-            if field.required:
-                errors.append(get_missing_field_error(loc=loc))
-            else:
-                values[field.name] = deepcopy(field.default)
+            _handle_missing_field_value(field, values, errors, loc)
             continue
 
         # Finally, validate the value
@@ -366,39 +361,64 @@ def _request_body_to_args(
     )
 
     for field in required_params:
-        # This sets the location to:
-        # { "user": { object } } if field.alias == user
-        # { { object } if field_alias is omitted
-        loc: tuple[str, ...] = ("body", field.alias)
-        if field_alias_omitted:
-            loc = ("body",)
-
-        value: Any | None = None
-
-        # Now that we know what to look for, try to get the value from the received body
-        if received_body is not None:
-            try:
-                value = received_body.get(field.alias)
-            except AttributeError:
-                errors.append(get_missing_field_error(loc))
-                continue
-
-        # Determine if the field is required
+        loc = _get_body_field_location(field, field_alias_omitted)
+        value = _extract_field_value_from_body(field, received_body, loc, errors)
+
+        # If we don't have a value, see if it's required or has a default
         if value is None:
-            if field.required:
-                errors.append(get_missing_field_error(loc))
-            else:
-                values[field.name] = deepcopy(field.default)
+            _handle_missing_field_value(field, values, errors, loc)
             continue
 
-        # MAINTENANCE: Handle byte and file fields
-
-        # Finally, validate the value
+        value = _normalize_field_value(field, value)
         values[field.name] = _validate_field(field=field, value=value, loc=loc, existing_errors=errors)
 
     return values, errors
 
 
+def _get_body_field_location(field: ModelField, field_alias_omitted: bool) -> tuple[str, ...]:
+    """Get the location tuple for a body field based on whether the field alias is omitted."""
+    if field_alias_omitted:
+        return ("body",)
+    return ("body", field.alias)
+
+
+def _extract_field_value_from_body(
+    field: ModelField,
+    received_body: dict[str, Any] | None,
+    loc: tuple[str, ...],
+    errors: list[dict[str, Any]],
+) -> Any | None:
+    """Extract field value from the received body, handling potential AttributeError."""
+    if received_body is None:
+        return None
+
+    try:
+        return received_body.get(field.alias)
+    except AttributeError:
+        errors.append(get_missing_field_error(loc))
+        return None
+
+
+def _handle_missing_field_value(
+    field: ModelField,
+    values: dict[str, Any],
+    errors: list[dict[str, Any]],
+    loc: tuple[str, ...],
+) -> None:
+    """Handle the case when a field value is missing."""
+    if field.required:
+        errors.append(get_missing_field_error(loc))
+    else:
+        values[field.name] = field.get_default()
+
+
+def _normalize_field_value(field: ModelField, value: Any) -> Any:
+    """Normalize field value, converting lists to single values for non-sequence fields."""
+    if isinstance(value, list) and not is_sequence_field(field):
+        return value[0]
+    return value
+
+
 def _validate_field(
     *,
     field: ModelField,

aws_lambda_powertools/shared/version.py

@@ -1,3 +1,3 @@
 """Exposes version constant to avoid circular dependencies."""
 
-VERSION = "3.20.1a1"
+VERSION = "3.20.1a6"

aws_lambda_powertools/utilities/kafka/schema_config.py

@@ -60,7 +60,7 @@ def __init__(
         value_schema_type: Literal["AVRO", "PROTOBUF", "JSON"] | None = None,
         value_schema: str | None = None,
         value_output_serializer: Any | None = None,
-        key_schema_type: Literal["AVRO", "PROTOBUF", "JSON", None] | None = None,
+        key_schema_type: Literal["AVRO", "PROTOBUF", "JSON"] | None = None,
         key_schema: str | None = None,
         key_output_serializer: Any | None = None,
     ):

aws_lambda_powertools/utilities/parameters/types.py

@@ -1,3 +1,3 @@
 from typing import Literal
 
-TransformOptions = Literal["json", "binary", "auto", None]
+TransformOptions = Literal["json", "binary", "auto", None]  # noqa PYI061

docs/Dockerfile

@@ -1,5 +1,5 @@
 # v9.1.18
-FROM squidfunk/mkdocs-material@sha256:209b62dd9530163cc5cf9a49853b5bb8570ffb3f3b5fe4eadc1d319bbda5ce2f
+FROM squidfunk/mkdocs-material@sha256:86d21da4f45f16e30774bf911e5b4795da13ce0cd197dbf8d3d059f256b2cc37
 # pip-compile --generate-hashes --output-file=requirements.txt requirements.in
 COPY requirements.txt /tmp/
 RUN pip install --require-hashes -r /tmp/requirements.txt

docs/core/event_handler/api_gateway.md

@@ -1144,7 +1144,7 @@ You can enable debug mode via `debug` param, or via `POWERTOOLS_DEV` [environmen
 This will enable full tracebacks errors in the response, print request and responses, and set CORS in development mode.
 
 ???+ danger
-    This might reveal sensitive information in your logs and relax CORS restrictions, use it sparingly.
+    This might reveal sensitive information in your logs, use it sparingly.
 
     It's best to use for local development only!
 

docs/core/logger.md

@@ -375,7 +375,7 @@ If you want to access the numeric value of the current log level, you can use th
     When you want to set a logging policy to drop informational or verbose logs for one or all AWS Lambda functions, regardless of runtime and logger used.
 
 <!-- markdownlint-disable MD013 -->
-With [AWS Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-advanced){target="_blank"}, you can enforce a minimum log level that Lambda will accept from your application code.
+With [AWS Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs-log-level.html#monitoring-cloudwatchlogs-log-level-setting){target="_blank"}, you can enforce a minimum log level that Lambda will accept from your application code.
 
 When enabled, you should keep `Logger` and ALC log level in sync to avoid data loss.
 
@@ -409,6 +409,11 @@ We prioritise log level settings in this order:
 2. Explicit log level in `Logger` constructor, or by calling the `logger.setLevel()` method
 3. `POWERTOOLS_LOG_LEVEL` environment variable
 
+!!! info "AWS CDK and Advanced Logging Controls"
+    When using AWS CDK's `applicationLogLevelV2` parameter or setting log levels through the Lambda console, AWS Lambda automatically sets the `AWS_LAMBDA_LOG_LEVEL` environment variable. This means Lambda's log level takes precedence over Powertools for AWS configuration, potentially overriding both `POWERTOOLS_LOG_LEVEL` and sampling settings.
+
+    **Example**: If you set `applicationLogLevelV2=DEBUG` in CDK while having `POWERTOOLS_LOG_LEVEL=INFO`, the DEBUG level will be used because Lambda automatically sets the environment variable `AWS_LAMBDA_LOG_LEVEL` to the debug level.
+
 If you set `Logger` level lower than ALC, we will emit a warning informing you that your messages will be discarded by Lambda.
 
 > **NOTE**
@@ -825,6 +830,8 @@ Use sampling when you want to dynamically change your log level to **DEBUG** bas
 
 You can use values ranging from `0.0` to `1` (100%) when setting `POWERTOOLS_LOGGER_SAMPLE_RATE` env var, or `sampling_rate` parameter in Logger.
 
+**AWS Lambda Advanced Logging Controls (ALC)** settings can affect Sampling behavior. See [how it works](#aws-lambda-advanced-logging-controls-alc).
+
 ???+ tip "Tip: When is this useful?"
     Log sampling allows you to capture debug information for a fraction of your requests, helping you diagnose rare or intermittent issues without increasing the overall verbosity of your logs.