Merge branch 'develop' into dependabot/npm_and_yarn/develop/aws-cdk-8aaedd9ff9

Author: leandrodamascena

.github/workflows/quality_check.yml

@@ -43,6 +43,7 @@ jobs:
   quality_check:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       max-parallel: 5
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]

CHANGELOG.md

@@ -5,15 +5,104 @@
 # Unreleased
 
 
+<a name="v3.26.0"></a>
+## [v3.26.0] - 2026-03-20
+## Features
+
+* add ldms feature ([#8051](https://github.com/aws-powertools/powertools-lambda-python/issues/8051))
+
+## Maintenance
+
+* version bump
+
+
 <a name="v3.25.0"></a>
 ## [v3.25.0] - 2026-03-12
 ## Bug Fixes
 
 * **ci:** remove DUB region ([#8031](https://github.com/aws-powertools/powertools-lambda-python/issues/8031))
+* **event-handler:** prevent OpenAPI schema bleed when reusing response dictionaries ([#7952](https://github.com/aws-powertools/powertools-lambda-python/issues/7952))
+* **event_handler:** add middleware validation per route ([#8020](https://github.com/aws-powertools/powertools-lambda-python/issues/8020))
+* **event_handler:** fix bug regression in Annotated field ([#7904](https://github.com/aws-powertools/powertools-lambda-python/issues/7904))
+* **event_handler:** return 415 status_code for unsupported content-type headers ([#7980](https://github.com/aws-powertools/powertools-lambda-python/issues/7980))
+* **event_handler:** sync alias and validation_alias for Pydantic 2.12+ compatibility ([#7901](https://github.com/aws-powertools/powertools-lambda-python/issues/7901))
+* **event_handler:** preserve openapi_examples on Body ([#7862](https://github.com/aws-powertools/powertools-lambda-python/issues/7862))
+* **logger:** preserve percent-style formatting args in flush_buffer ([#8009](https://github.com/aws-powertools/powertools-lambda-python/issues/8009))
+* **parameters:** fix variable shadowing in SSM parameter chunking ([#8006](https://github.com/aws-powertools/powertools-lambda-python/issues/8006))
+* **typing:** resolve ty diagnostics in logging and metrics modules ([#7953](https://github.com/aws-powertools/powertools-lambda-python/issues/7953))
+* **typing:** accept Mapping type in resolve() for event parameter ([#7909](https://github.com/aws-powertools/powertools-lambda-python/issues/7909))
+
+## Code Refactoring
+
+* **batch:** improve type annotation for event parameter ([#7924](https://github.com/aws-powertools/powertools-lambda-python/issues/7924))
+
+## Documentation
+
+* clarify append_context_keys behavior with overlapping keys ([#7846](https://github.com/aws-powertools/powertools-lambda-python/issues/7846))
+
+## Features
+
+* Add a flag to ALBResolver to URL-decode query parameters ([#7940](https://github.com/aws-powertools/powertools-lambda-python/issues/7940))
+* add HttpResolverAlpha resolver ([#7913](https://github.com/aws-powertools/powertools-lambda-python/issues/7913))
+* **decorators:** Support Durable Context in logger and metric decorators ([#7765](https://github.com/aws-powertools/powertools-lambda-python/issues/7765))
+* **event-handler:** add per-route validation support ([#7965](https://github.com/aws-powertools/powertools-lambda-python/issues/7965))
+* **event_source:** add support for S3 IntelligentTiering events ([#7954](https://github.com/aws-powertools/powertools-lambda-python/issues/7954))
+* **metrics:** add support for multiple dimension sets ([#7848](https://github.com/aws-powertools/powertools-lambda-python/issues/7848))
+* **openapi:** add support for micro Lambda pattern ([#7920](https://github.com/aws-powertools/powertools-lambda-python/issues/7920))
 
 ## Maintenance
 
+* remove unused PR automation workflows ([#8008](https://github.com/aws-powertools/powertools-lambda-python/issues/8008))
+* adding fuzzing tests ([#7903](https://github.com/aws-powertools/powertools-lambda-python/issues/7903))
+* update swagger ui files ([#7914](https://github.com/aws-powertools/powertools-lambda-python/issues/7914))
 * version bump
+* **ci:** new pre-release 3.24.1a1 ([#7926](https://github.com/aws-powertools/powertools-lambda-python/issues/7926))
+* **deps:** bump jmespath from 1.0.1 to 1.1.0 ([#7970](https://github.com/aws-powertools/powertools-lambda-python/issues/7970))
+* **deps:** bump urllib3 from 2.6.0 to 2.6.3 in /docs ([#7921](https://github.com/aws-powertools/powertools-lambda-python/issues/7921))
+* **deps:** bump squidfunk/mkdocs-material from `3bba0a9` to `8f41b60` in /docs ([#8010](https://github.com/aws-powertools/powertools-lambda-python/issues/8010))
+* **deps:** bump the github-actions group with 4 updates ([#8013](https://github.com/aws-powertools/powertools-lambda-python/issues/8013))
+* **deps:** bump protobuf from 6.33.2 to 6.33.4 ([#7948](https://github.com/aws-powertools/powertools-lambda-python/issues/7948))
+* **deps:** bump valkey-glide from 2.2.3 to 2.2.5 ([#7947](https://github.com/aws-powertools/powertools-lambda-python/issues/7947))
+* **deps:** bump actions/dependency-review-action from 4.8.2 to 4.8.3 in the github-actions group ([#8004](https://github.com/aws-powertools/powertools-lambda-python/issues/8004))
+* **deps:** bump cryptography from 46.0.3 to 46.0.5 ([#7991](https://github.com/aws-powertools/powertools-lambda-python/issues/7991))
+* **deps:** bump the github-actions group with 3 updates ([#7960](https://github.com/aws-powertools/powertools-lambda-python/issues/7960))
+* **deps:** bump protobuf from 6.33.4 to 6.33.5 ([#7977](https://github.com/aws-powertools/powertools-lambda-python/issues/7977))
+* **deps:** bump datadog-lambda from 8.120.0 to 8.121.0 ([#8015](https://github.com/aws-powertools/powertools-lambda-python/issues/8015))
+* **deps:** bump the github-actions group with 3 updates ([#7971](https://github.com/aws-powertools/powertools-lambda-python/issues/7971))
+* **deps:** bump the github-actions group with 2 updates ([#7985](https://github.com/aws-powertools/powertools-lambda-python/issues/7985))
+* **deps-dev:** bump the dev-dependencies group with 2 updates ([#7969](https://github.com/aws-powertools/powertools-lambda-python/issues/7969))
+* **deps-dev:** bump cdklabs-generative-ai-cdk-constructs from 0.1.312 to 0.1.314 ([#7973](https://github.com/aws-powertools/powertools-lambda-python/issues/7973))
+* **deps-dev:** bump cfn-lint from 1.43.3 to 1.43.4 ([#7972](https://github.com/aws-powertools/powertools-lambda-python/issues/7972))
+* **deps-dev:** bump aws-cdk-lib from 2.233.0 to 2.236.0 ([#7974](https://github.com/aws-powertools/powertools-lambda-python/issues/7974))
+* **deps-dev:** bump aws-cdk from 2.1103.0 to 2.1105.0 in the aws-cdk group ([#7982](https://github.com/aws-powertools/powertools-lambda-python/issues/7982))
+* **deps-dev:** bump aws-cdk from 2.1101.0 to 2.1103.0 in the aws-cdk group ([#7967](https://github.com/aws-powertools/powertools-lambda-python/issues/7967))
+* **deps-dev:** bump sentry-sdk from 2.48.0 to 2.52.0 ([#7987](https://github.com/aws-powertools/powertools-lambda-python/issues/7987))
+* **deps-dev:** bump testcontainers from 4.14.0 to 4.14.1 ([#7988](https://github.com/aws-powertools/powertools-lambda-python/issues/7988))
+* **deps-dev:** bump cfn-lint from 1.43.2 to 1.43.3 ([#7958](https://github.com/aws-powertools/powertools-lambda-python/issues/7958))
+* **deps-dev:** bump testcontainers from 4.13.3 to 4.14.0 ([#7959](https://github.com/aws-powertools/powertools-lambda-python/issues/7959))
+* **deps-dev:** bump multiprocess from 0.70.18 to 0.70.19 ([#7961](https://github.com/aws-powertools/powertools-lambda-python/issues/7961))
+* **deps-dev:** bump aws-cdk from 2.1100.3 to 2.1101.0 in the aws-cdk group ([#7955](https://github.com/aws-powertools/powertools-lambda-python/issues/7955))
+* **deps-dev:** bump ruff from 0.14.11 to 0.14.13 in the dev-dependencies group ([#7957](https://github.com/aws-powertools/powertools-lambda-python/issues/7957))
+* **deps-dev:** bump bandit from 1.9.2 to 1.9.3 ([#7962](https://github.com/aws-powertools/powertools-lambda-python/issues/7962))
+* **deps-dev:** bump aws-cdk-lib from 2.237.1 to 2.238.0 ([#7986](https://github.com/aws-powertools/powertools-lambda-python/issues/7986))
+* **deps-dev:** bump virtualenv from 20.35.4 to 20.36.1 ([#7950](https://github.com/aws-powertools/powertools-lambda-python/issues/7950))
+* **deps-dev:** bump aws-cdk from 2.1100.2 to 2.1100.3 in the aws-cdk group ([#7942](https://github.com/aws-powertools/powertools-lambda-python/issues/7942))
+* **deps-dev:** bump boto3-stubs from 1.42.21 to 1.42.26 ([#7945](https://github.com/aws-powertools/powertools-lambda-python/issues/7945))
+* **deps-dev:** bump aws-cdk from 2.1105.0 to 2.1106.0 in the aws-cdk group ([#7995](https://github.com/aws-powertools/powertools-lambda-python/issues/7995))
+* **deps-dev:** bump ruff from 0.14.10 to 0.14.11 in the dev-dependencies group ([#7944](https://github.com/aws-powertools/powertools-lambda-python/issues/7944))
+* **deps-dev:** bump filelock from 3.20.2 to 3.20.3 ([#7946](https://github.com/aws-powertools/powertools-lambda-python/issues/7946))
+* **deps-dev:** bump filelock from 3.20.3 to 3.24.2 ([#7999](https://github.com/aws-powertools/powertools-lambda-python/issues/7999))
+* **deps-dev:** bump sentry-sdk from 2.52.0 to 2.53.0 ([#7998](https://github.com/aws-powertools/powertools-lambda-python/issues/7998))
+* **deps-dev:** bump urllib3 from 2.6.2 to 2.6.3 in /layer_v3 ([#7928](https://github.com/aws-powertools/powertools-lambda-python/issues/7928))
+* **deps-dev:** bump types-python-dateutil from 2.9.0.20251115 to 2.9.0.20260124 ([#7989](https://github.com/aws-powertools/powertools-lambda-python/issues/7989))
+* **deps-dev:** bump aws-cdk-aws-lambda-python-alpha from 2.233.0a0 to 2.238.0a0 ([#7997](https://github.com/aws-powertools/powertools-lambda-python/issues/7997))
+* **deps-dev:** bump cfn-lint from 1.44.0 to 1.46.0 ([#8018](https://github.com/aws-powertools/powertools-lambda-python/issues/8018))
+* **deps-dev:** bump aws-cdk from 2.1106.0 to 2.1108.0 in the aws-cdk group ([#8011](https://github.com/aws-powertools/powertools-lambda-python/issues/8011))
+* **deps-dev:** bump cfn-lint from 1.43.1 to 1.43.2 ([#7907](https://github.com/aws-powertools/powertools-lambda-python/issues/7907))
+* **deps-dev:** bump aws-cdk from 2.1100.1 to 2.1100.2 in the aws-cdk group ([#7905](https://github.com/aws-powertools/powertools-lambda-python/issues/7905))
+* **deps-dev:** bump filelock from 3.24.2 to 3.25.0 ([#8016](https://github.com/aws-powertools/powertools-lambda-python/issues/8016))
+* **deps-dev:** bump urllib3 from 2.6.2 to 2.6.3 ([#7922](https://github.com/aws-powertools/powertools-lambda-python/issues/7922))
+* **typing:** add ty type checker to CI with baseline exclusions  ([#7938](https://github.com/aws-powertools/powertools-lambda-python/issues/7938))
 
 
 <a name="v3.24.0"></a>
@@ -7462,7 +7551,8 @@
 * Merge pull request [#5](https://github.com/aws-powertools/powertools-lambda-python/issues/5) from jfuss/feat/python38
 
 
-[Unreleased]: https://github.com/aws-powertools/powertools-lambda-python/compare/v3.25.0...HEAD
+[Unreleased]: https://github.com/aws-powertools/powertools-lambda-python/compare/v3.26.0...HEAD
+[v3.26.0]: https://github.com/aws-powertools/powertools-lambda-python/compare/v3.25.0...v3.26.0
 [v3.25.0]: https://github.com/aws-powertools/powertools-lambda-python/compare/v3.24.0...v3.25.0
 [v3.24.0]: https://github.com/aws-powertools/powertools-lambda-python/compare/v3.23.0...v3.24.0
 [v3.23.0]: https://github.com/aws-powertools/powertools-lambda-python/compare/v3.22.1...v3.23.0

aws_lambda_powertools/shared/constants.py

@@ -67,5 +67,12 @@
 PRETTY_INDENT: int = 4
 COMPACT_INDENT: None = None
 
+# Metadata constants
+LAMBDA_METADATA_API_ENV: str = "AWS_LAMBDA_METADATA_API"
+LAMBDA_METADATA_TOKEN_ENV: str = "AWS_LAMBDA_METADATA_TOKEN"
+METADATA_API_VERSION: str = "2026-01-15"
+METADATA_PATH: str = "/metadata/execution-environment"
+METADATA_DEFAULT_TIMEOUT_SECS: float = 1.0
+
 # Idempotency constants
 IDEMPOTENCY_DISABLED_ENV: str = "POWERTOOLS_IDEMPOTENCY_DISABLED"

aws_lambda_powertools/shared/version.py

@@ -1,3 +1,3 @@
 """Exposes version constant to avoid circular dependencies."""
 
-VERSION = "3.25.0"
+VERSION = "3.26.0"

aws_lambda_powertools/utilities/metadata/__init__.py

@@ -0,0 +1,17 @@
+"""
+Utility to fetch data from the AWS Lambda Metadata Endpoint
+"""
+
+from aws_lambda_powertools.utilities.metadata.exceptions import LambdaMetadataError
+from aws_lambda_powertools.utilities.metadata.lambda_metadata import (
+    LambdaMetadata,
+    clear_metadata_cache,
+    get_lambda_metadata,
+)
+
+__all__ = [
+    "LambdaMetadata",
+    "LambdaMetadataError",
+    "get_lambda_metadata",
+    "clear_metadata_cache",
+]

aws_lambda_powertools/utilities/metadata/exceptions.py

@@ -0,0 +1,11 @@
+"""
+Lambda Metadata Service exceptions
+"""
+
+
+class LambdaMetadataError(Exception):
+    """Raised when the Lambda Metadata Endpoint is unavailable or returns an error."""
+
+    def __init__(self, message: str, status_code: int = -1):
+        self.status_code = status_code
+        super().__init__(message)

aws_lambda_powertools/utilities/metadata/lambda_metadata.py

@@ -0,0 +1,174 @@
+"""
+Lambda Metadata Service client
+
+Fetches execution environment metadata from the Lambda Metadata Endpoint,
+with caching for the sandbox lifetime.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import urllib.request
+from dataclasses import dataclass, field
+from json import JSONDecodeError
+from json import loads as json_loads
+from typing import Any
+
+from aws_lambda_powertools.shared.constants import (
+    LAMBDA_INITIALIZATION_TYPE,
+    LAMBDA_METADATA_API_ENV,
+    LAMBDA_METADATA_TOKEN_ENV,
+    METADATA_API_VERSION,
+    METADATA_DEFAULT_TIMEOUT_SECS,
+    METADATA_PATH,
+    POWERTOOLS_DEV_ENV,
+)
+from aws_lambda_powertools.utilities.metadata.exceptions import LambdaMetadataError
+
+logger = logging.getLogger(__name__)
+
+_cache: dict[str, Any] = {}
+
+
+@dataclass(frozen=True)
+class LambdaMetadata:
+    """Lambda execution environment metadata returned by the metadata endpoint."""
+
+    availability_zone_id: str | None = None
+    """The Availability Zone ID where the function is executing (e.g. ``use1-az1``)."""
+
+    _raw: dict[str, Any] = field(default_factory=dict, repr=False)
+    """Full raw response for forward-compatibility with future fields."""
+
+
+def _is_lambda_environment() -> bool:
+    """Check whether we are running inside a Lambda execution environment."""
+    return os.environ.get(LAMBDA_INITIALIZATION_TYPE, "") != ""
+
+
+def _is_dev_mode() -> bool:
+    """Check whether POWERTOOLS_DEV is enabled."""
+    return os.environ.get(POWERTOOLS_DEV_ENV, "false").strip().lower() in ("true", "1")
+
+
+def _build_metadata(data: dict[str, Any]) -> LambdaMetadata:
+    """Build a LambdaMetadata dataclass from the raw endpoint response."""
+    return LambdaMetadata(
+        availability_zone_id=data.get("AvailabilityZoneID"),
+        _raw=data,
+    )
+
+
+def _fetch_metadata(timeout: float = METADATA_DEFAULT_TIMEOUT_SECS) -> dict[str, Any]:
+    """
+    Fetch metadata from the Lambda Metadata Endpoint via HTTP.
+
+    Parameters
+    ----------
+    timeout : float
+        Request timeout in seconds.
+
+    Returns
+    -------
+    dict[str, Any]
+        Parsed JSON response from the metadata endpoint.
+
+    Raises
+    ------
+    LambdaMetadataError
+        If required environment variables are missing, the endpoint returns
+        a non-200 status, or the response cannot be parsed.
+    """
+    api = os.environ.get(LAMBDA_METADATA_API_ENV)
+    token = os.environ.get(LAMBDA_METADATA_TOKEN_ENV)
+
+    if not api:
+        raise LambdaMetadataError(
+            f"Environment variable {LAMBDA_METADATA_API_ENV} is not set. Ensure {LAMBDA_METADATA_API_ENV} is set.",
+        )
+    if not token:
+        raise LambdaMetadataError(
+            f"Environment variable {LAMBDA_METADATA_TOKEN_ENV} is not set. Ensure {LAMBDA_METADATA_TOKEN_ENV} is set.",
+        )
+
+    url = f"http://{api}/{METADATA_API_VERSION}{METADATA_PATH}"
+    logger.debug("Fetching Lambda metadata from: %s", url)
+
+    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosec B310
+            status = resp.status
+            body = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        raise LambdaMetadataError(
+            f"Metadata request failed with status {exc.code}",
+            status_code=exc.code,
+        ) from exc
+    except Exception as exc:
+        raise LambdaMetadataError(f"Failed to fetch Lambda metadata: {exc}") from exc
+
+    if status != 200:
+        raise LambdaMetadataError(
+            f"Metadata request failed with status {status}",
+            status_code=status,
+        )
+
+    try:
+        data: dict[str, Any] = json_loads(body)
+    except (JSONDecodeError, TypeError) as exc:
+        raise LambdaMetadataError(f"Failed to parse metadata response: {exc}") from exc
+
+    logger.debug("Lambda metadata response: %s", data)
+    return data
+
+
+def get_lambda_metadata(*, timeout: float = METADATA_DEFAULT_TIMEOUT_SECS) -> LambdaMetadata:
+    """
+    Retrieve Lambda execution environment metadata.
+
+    Returns cached metadata on subsequent calls. When not running in a Lambda
+    environment (local dev, tests) or when ``POWERTOOLS_DEV`` is enabled,
+    returns an empty ``LambdaMetadata``.
+
+    Parameters
+    ----------
+    timeout : float
+        HTTP request timeout in seconds (default 1.0).
+
+    Returns
+    -------
+    LambdaMetadata
+        Metadata about the current execution environment.
+
+    Raises
+    ------
+    LambdaMetadataError
+        If the metadata endpoint is unavailable or returns an error.
+
+    Example
+    -------
+        >>> from aws_lambda_powertools.utilities.metadata import get_lambda_metadata
+        >>> metadata = get_lambda_metadata()
+        >>> metadata.availability_zone_id  # e.g. "use1-az1"
+    """
+    if _is_dev_mode() or not _is_lambda_environment():
+        return LambdaMetadata()
+
+    if _cache:
+        return _build_metadata(_cache)
+
+    data = _fetch_metadata(timeout=timeout)
+    _cache.update(data)
+    return _build_metadata(_cache)
+
+
+def clear_metadata_cache() -> None:
+    """
+    Clear the cached metadata.
+
+    Useful for testing or when you need to force a fresh fetch
+    (e.g. after SnapStart restore).
+    """
+    _cache.clear()