aws-lambda-powertools 3.31.0__tar.gz → 3.34.0__tar.gz

{aws_lambda_powertools-3.31.0 → aws_lambda_powertools-3.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: aws_lambda_powertools
-Version: 3.31.0
+Version: 3.34.0
 Summary: Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverless best practices and increase developer velocity.
 License: MIT
 Keywords: aws_lambda_powertools,aws,tracing,logging,lambda,powertools,feature_flags,idempotency,middleware
@@ -29,7 +29,7 @@ Provides-Extra: tracer
 Provides-Extra: validation
 Provides-Extra: valkey
 Requires-Dist: avro (>=1.12.0,<2.0.0) ; extra == "kafka-consumer-avro"
-Requires-Dist: aws-encryption-sdk (>=3.3.1,!=4.0.0,!=4.0.1,!=4.0.2,!=4.0.3,!=4.0.4,<5.0.0) ; extra == "all" or extra == "datamasking"
+Requires-Dist: aws-encryption-sdk (>=4.0.5,<5.0.0) ; extra == "all" or extra == "datamasking"
 Requires-Dist: aws-xray-sdk (>=2.8.0,<3.0.0) ; extra == "tracer" or extra == "all"
 Requires-Dist: boto3 (>=1.34.32,<2.0.0) ; extra == "aws-sdk"
 Requires-Dist: datadog-lambda (>=8.114.0,<9.0.0) ; extra == "datadog"

{aws_lambda_powertools-3.31.0 → aws_lambda_powertools-3.34.0}/aws_lambda_powertools/event_handler/events_appsync/appsync_events.py

@@ -321,7 +321,7 @@ class AppSyncEventsResolver(Router):
                     if isinstance(ret, Exception)
                     else {"id": e.get("id"), "payload": ret}
                 )
-                for e, ret in zip(self.current_event.events, results)
+                for e, ret in zip(self.current_event.events, results, strict=True)
             ],
         )
 

{aws_lambda_powertools-3.31.0 → aws_lambda_powertools-3.34.0}/aws_lambda_powertools/event_handler/openapi/dependant.py

@@ -156,6 +156,7 @@ def get_dependant(
     call: Callable[..., Any],
     name: str | None = None,
     responses: dict[int, OpenAPIResponse] | None = None,
+    is_dependency: bool = False,
 ) -> Dependant:
     """
     Returns a dependant model for a handler function. A dependant model is a model that contains
@@ -200,6 +201,7 @@ def get_dependant(
             sub_dependant = get_dependant(
                 path=path,
                 call=depends_instance.dependency,
+                is_dependency=True,
             )
             dependant.dependencies.append(
                 DependencyParam(
@@ -229,7 +231,12 @@ def get_dependant(
         else:
             add_param_to_fields(field=param_field, dependant=dependant)
 
-    _add_return_annotation(dependant, endpoint_signature)
+    # A dependency's return value is injected directly into the handler, never serialized as a
+    # response body nor validated as an OpenAPI parameter — so building a Pydantic schema for it is
+    # both unused (no reader consumes a sub-dependency's return_param) and actively harmful: it crashes
+    # for arbitrary return types (e.g. boto3/botocore clients). Only the top-level handler needs it.
+    if not is_dependency:
+        _add_return_annotation(dependant, endpoint_signature)
     _add_extra_responses(dependant, responses)
 
     return dependant

{aws_lambda_powertools-3.31.0 → aws_lambda_powertools-3.34.0}/aws_lambda_powertools/event_handler/openapi/schema_generator.py

@@ -174,9 +174,15 @@ def _build_operation_parameters(
             continue
 
         if _is_pydantic_model_param(field_info):
-            parameters.extend(_expand_pydantic_model_parameters(field_info))
+            generated_parameters = _expand_pydantic_model_parameters(field_info)
         else:
-            parameters.append(_create_regular_parameter(param, model_name_map, field_mapping))
+            generated_parameters = [_create_regular_parameter(param, model_name_map, field_mapping)]
+
+        parameters.extend(
+            parameter
+            for parameter in generated_parameters
+            if not (parameter["in"] == "header" and parameter["name"].lower() == "content-type")
+        )
 
     return parameters
 

{aws_lambda_powertools-3.31.0 → aws_lambda_powertools-3.34.0}/aws_lambda_powertools/shared/version.py

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

{aws_lambda_powertools-3.31.0 → aws_lambda_powertools-3.34.0}/aws_lambda_powertools/tracing/base.py

@@ -14,6 +14,7 @@ if TYPE_CHECKING:
     import numbers
     import traceback
     from collections.abc import Generator, Sequence
+    from contextlib import AbstractAsyncContextManager
 
 
 class BaseSegment(abc.ABC):
@@ -99,8 +100,7 @@ class BaseProvider(abc.ABC):
         """
 
     @abc.abstractmethod
-    @contextmanager
-    def in_subsegment_async(self, name=None, **kwargs) -> Generator[BaseSegment, None, None]:
+    def in_subsegment_async(self, name=None, **kwargs) -> AbstractAsyncContextManager[BaseSegment]:
         """Return a subsegment async context manger.
 
         Parameters

aws_lambda_powertools-3.34.0/aws_lambda_powertools/utilities/circuit_breaker/__init__.py

@@ -0,0 +1,29 @@
+"""
+Circuit Breaker utility for protecting unhealthy downstream dependencies.
+"""
+
+from aws_lambda_powertools.utilities.circuit_breaker.circuit_breaker import circuit_breaker
+from aws_lambda_powertools.utilities.circuit_breaker.config import CircuitBreakerConfig
+from aws_lambda_powertools.utilities.circuit_breaker.exceptions import (
+    CircuitBreakerConfigError,
+    CircuitBreakerError,
+    CircuitBreakerOpenError,
+    CircuitBreakerPersistenceError,
+)
+from aws_lambda_powertools.utilities.circuit_breaker.states import (
+    CircuitInfo,
+    CircuitState,
+    CircuitTransition,
+)
+
+__all__ = (
+    "circuit_breaker",
+    "CircuitBreakerConfig",
+    "CircuitInfo",
+    "CircuitState",
+    "CircuitTransition",
+    "CircuitBreakerError",
+    "CircuitBreakerOpenError",
+    "CircuitBreakerConfigError",
+    "CircuitBreakerPersistenceError",
+)

{aws_lambda_powertools-3.31.0/aws_lambda_powertools/utilities/circuit_breaker_alpha → aws_lambda_powertools-3.34.0/aws_lambda_powertools/utilities/circuit_breaker}/base.py

@@ -10,20 +10,22 @@ from __future__ import annotations
 
 import datetime
 import logging
+import os
+import threading
 import uuid
 from typing import TYPE_CHECKING, Any
 
-from aws_lambda_powertools.utilities.circuit_breaker_alpha.exceptions import CircuitBreakerOpenError
-from aws_lambda_powertools.utilities.circuit_breaker_alpha.states import CircuitState, CircuitTransition
+from aws_lambda_powertools.utilities.circuit_breaker.exceptions import CircuitBreakerOpenError
+from aws_lambda_powertools.utilities.circuit_breaker.states import CircuitState, CircuitTransition
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from aws_lambda_powertools.utilities.circuit_breaker_alpha.config import CircuitBreakerConfig
-    from aws_lambda_powertools.utilities.circuit_breaker_alpha.persistence.base import (
+    from aws_lambda_powertools.utilities.circuit_breaker.config import CircuitBreakerConfig
+    from aws_lambda_powertools.utilities.circuit_breaker.persistence.base import (
         CircuitBreakerPersistenceLayer,
     )
-    from aws_lambda_powertools.utilities.circuit_breaker_alpha.states import CircuitInfo
+    from aws_lambda_powertools.utilities.circuit_breaker.states import CircuitInfo
 
 logger = logging.getLogger(__name__)
 
@@ -37,8 +39,31 @@ _LOCAL_SUCCESSES: dict[str, int] = {}
 # recovered), so stale local failure streaks can be invalidated.
 _LAST_OBSERVED_STATE: dict[str, CircuitState] = {}
 
-# Stable per-environment identifier used to claim the half-open probe lock.
-_ENVIRONMENT_ID = uuid.uuid4().hex
+# Guards the three dicts above. Increments are read-modify-write and a threshold
+# crossing must be observed by exactly one thread, so every access goes through this
+# lock. Held only while mutating the dicts, never across persistence writes or user
+# callbacks.
+_COUNTERS_LOCK = threading.Lock()
+
+# Identifier used to claim the half-open probe lock, unique per thread so the store's
+# conditional election picks a single prober across threads as well as processes.
+_PROBE_OWNER = threading.local()
+
+
+def _probe_owner_id() -> str:
+    """
+    Return this thread's stable probe-owner identifier, minting it on first use.
+
+    A uuid in thread-local storage rather than ``threading.get_ident()``: the OS reuses
+    thread ids, and a recycled id would let an unrelated thread pass the owner check and
+    probe alongside the real owner. The pid check re-mints the id in forked children,
+    which inherit the forking thread's local storage.
+    """
+    pid = os.getpid()
+    if getattr(_PROBE_OWNER, "pid", None) != pid:
+        _PROBE_OWNER.id = f"{pid}#{uuid.uuid4().hex}"
+        _PROBE_OWNER.pid = pid
+    return _PROBE_OWNER.id
 
 
 class CircuitBreakerHandler:
@@ -111,32 +136,35 @@ class CircuitBreakerHandler:
             # If we previously observed a non-CLOSED state and the circuit is now back to
             # CLOSED, another environment completed the recovery cycle. Reset local counters
             # so a stale partial failure streak doesn't immediately re-trip the circuit.
-            prev = _LAST_OBSERVED_STATE.get(self.name)
-            if prev is not None and prev != CircuitState.CLOSED:
-                _LOCAL_FAILURES[self.name] = 0
-            _LAST_OBSERVED_STATE[self.name] = CircuitState.CLOSED
+            with _COUNTERS_LOCK:
+                prev = _LAST_OBSERVED_STATE.get(self.name)
+                if prev is not None and prev != CircuitState.CLOSED:
+                    _LOCAL_FAILURES[self.name] = 0
+                _LAST_OBSERVED_STATE[self.name] = CircuitState.CLOSED
             return self._call_closed()
 
         if record.state == CircuitState.OPEN:
-            _LAST_OBSERVED_STATE[self.name] = CircuitState.OPEN
+            with _COUNTERS_LOCK:
+                _LAST_OBSERVED_STATE[self.name] = CircuitState.OPEN
             # ``opened_at`` may legitimately be 0 (epoch); treat only None as missing.
             opened_at = record.opened_at if record.opened_at is not None else self._now()
             if self._now() >= opened_at + self.config.recovery_timeout:
                 # Recovery window elapsed: try to become the single prober.
-                if self.persistence_store.try_acquire_half_open(self.name, _ENVIRONMENT_ID, opened_at):
+                if self.persistence_store.try_acquire_half_open(self.name, _probe_owner_id(), opened_at):
                     self._notify(CircuitState.OPEN, CircuitState.HALF_OPEN, opened_at=opened_at)
                     return self._call_probe()
             return self._open_response(record.to_circuit_info())
 
-        # HALF_OPEN: only the environment that owns the probe lock runs.
-        _LAST_OBSERVED_STATE[self.name] = CircuitState.HALF_OPEN
-        if record.half_open_owner == _ENVIRONMENT_ID:
+        # HALF_OPEN: only the thread that owns the probe lock runs.
+        with _COUNTERS_LOCK:
+            _LAST_OBSERVED_STATE[self.name] = CircuitState.HALF_OPEN
+        if record.half_open_owner == _probe_owner_id():
             return self._call_probe()
 
         # If the probe lease has expired (owner recycled mid-probe), take over.
         if record.probe_lease_expiry is not None and self._now() >= record.probe_lease_expiry:
             logger.debug("Circuit '%s' probe lease expired; attempting takeover.", self.name)
-            if self.persistence_store.try_acquire_half_open(self.name, _ENVIRONMENT_ID, record.opened_at or 0):
+            if self.persistence_store.try_acquire_half_open(self.name, _probe_owner_id(), record.opened_at or 0):
                 return self._call_probe()
 
         return self._open_response(record.to_circuit_info())
@@ -148,9 +176,14 @@ class CircuitBreakerHandler:
         except Exception as exc:
             if not self.config.counts_as_failure(exc):
                 raise
-            failures = _LOCAL_FAILURES.get(self.name, 0) + 1
-            _LOCAL_FAILURES[self.name] = failures
-            if failures >= self.config.failure_threshold:
+            # Increment and reset atomically so exactly one thread observes the threshold
+            # crossing; racing threads would otherwise lose increments (tripping late) or
+            # each persist the same transition.
+            with _COUNTERS_LOCK:
+                failures = _LOCAL_FAILURES.get(self.name, 0) + 1
+                tripped = failures >= self.config.failure_threshold
+                _LOCAL_FAILURES[self.name] = 0 if tripped else failures
+            if tripped:
                 logger.debug("Circuit '%s' tripping CLOSED to OPEN after %d failures.", self.name, failures)
                 opened_at = self._now()
                 self._safe_persist(
@@ -159,11 +192,11 @@ class CircuitBreakerHandler:
                     failure_count=failures,
                     opened_at=opened_at,
                 )
-                _LOCAL_FAILURES[self.name] = 0
                 self._notify(CircuitState.CLOSED, CircuitState.OPEN, opened_at=opened_at)
             raise
         else:
-            _LOCAL_FAILURES[self.name] = 0
+            with _COUNTERS_LOCK:
+                _LOCAL_FAILURES[self.name] = 0
             return result
 
     def _call_probe(self) -> Any:
@@ -176,17 +209,20 @@ class CircuitBreakerHandler:
             logger.debug("Circuit '%s' probe failed; reopening.", self.name)
             opened_at = self._now()
             self._safe_persist(self.persistence_store.save_reopen, self.name, opened_at=opened_at)
-            _LOCAL_SUCCESSES[self.name] = 0
+            with _COUNTERS_LOCK:
+                _LOCAL_SUCCESSES[self.name] = 0
             self._notify(CircuitState.HALF_OPEN, CircuitState.OPEN, opened_at=opened_at)
             raise
         else:
-            successes = _LOCAL_SUCCESSES.get(self.name, 0) + 1
-            _LOCAL_SUCCESSES[self.name] = successes
-            if successes >= self.config.success_threshold:
+            with _COUNTERS_LOCK:
+                successes = _LOCAL_SUCCESSES.get(self.name, 0) + 1
+                closed = successes >= self.config.success_threshold
+                _LOCAL_SUCCESSES[self.name] = 0 if closed else successes
+                if closed:
+                    _LOCAL_FAILURES[self.name] = 0
+            if closed:
                 logger.debug("Circuit '%s' closing after %d probe successes.", self.name, successes)
                 self._safe_persist(self.persistence_store.save_closed, self.name)
-                _LOCAL_SUCCESSES[self.name] = 0
-                _LOCAL_FAILURES[self.name] = 0
                 self._notify(CircuitState.HALF_OPEN, CircuitState.CLOSED)
             return result
 

{aws_lambda_powertools-3.31.0/aws_lambda_powertools/utilities/circuit_breaker_alpha → aws_lambda_powertools-3.34.0/aws_lambda_powertools/utilities/circuit_breaker}/circuit_breaker.py

@@ -12,14 +12,14 @@ from typing import TYPE_CHECKING, Any
 
 from aws_lambda_powertools.shared import constants
 from aws_lambda_powertools.shared.functions import strtobool
-from aws_lambda_powertools.utilities.circuit_breaker_alpha.base import CircuitBreakerHandler
-from aws_lambda_powertools.utilities.circuit_breaker_alpha.config import CircuitBreakerConfig
+from aws_lambda_powertools.utilities.circuit_breaker.base import CircuitBreakerHandler
+from aws_lambda_powertools.utilities.circuit_breaker.config import CircuitBreakerConfig
 from aws_lambda_powertools.warnings import PowertoolsUserWarning
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from aws_lambda_powertools.utilities.circuit_breaker_alpha.persistence.base import (
+    from aws_lambda_powertools.utilities.circuit_breaker.persistence.base import (
         CircuitBreakerPersistenceLayer,
     )
 
@@ -73,8 +73,8 @@ def circuit_breaker(
     -------
     **Protect a payment backend, buffering rejected requests**
 
-        from aws_lambda_powertools.utilities.circuit_breaker_alpha import circuit_breaker, CircuitInfo
-        from aws_lambda_powertools.utilities.circuit_breaker_alpha.persistence import (
+        from aws_lambda_powertools.utilities.circuit_breaker import circuit_breaker, CircuitInfo
+        from aws_lambda_powertools.utilities.circuit_breaker.persistence import (
             CircuitBreakerDynamoDBPersistence,
         )
 

{aws_lambda_powertools-3.31.0/aws_lambda_powertools/utilities/circuit_breaker_alpha → aws_lambda_powertools-3.34.0/aws_lambda_powertools/utilities/circuit_breaker}/config.py

@@ -4,7 +4,12 @@ Configuration for the Circuit Breaker utility.
 
 from __future__ import annotations
 
-from aws_lambda_powertools.utilities.circuit_breaker_alpha.exceptions import CircuitBreakerConfigError
+from typing import TYPE_CHECKING
+
+from aws_lambda_powertools.utilities.circuit_breaker.exceptions import CircuitBreakerConfigError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
 
 
 class CircuitBreakerConfig:
@@ -24,12 +29,14 @@ class CircuitBreakerConfig:
     success_threshold : int
         Number of *consecutive* probe successes required to close a half-open circuit.
         Defaults to 3.
-    handled_exceptions : tuple[type[Exception], ...] | None
+    handled_exceptions : type[Exception] | Iterable[type[Exception]] | None
         Allowlist: only these exception types count as failures; anything else
-        propagates without affecting the circuit. Mutually exclusive with
+        propagates without affecting the circuit. Accepts a single exception type or
+        an iterable of them (normalized to a tuple). Mutually exclusive with
         ``ignored_exceptions``. Defaults to ``None`` (treated as ``(Exception,)``).
-    ignored_exceptions : tuple[type[Exception], ...] | None
-        Denylist: every exception counts as a failure *except* these. Mutually
+    ignored_exceptions : type[Exception] | Iterable[type[Exception]] | None
+        Denylist: every exception counts as a failure *except* these. Accepts a single
+        exception type or an iterable of them (normalized to a tuple). Mutually
         exclusive with ``handled_exceptions``. Defaults to ``None``.
     local_cache_max_age : int
         Seconds a circuit's state is cached in the execution environment before a
@@ -38,8 +45,9 @@ class CircuitBreakerConfig:
     Raises
     ------
     CircuitBreakerConfigError
-        If both ``handled_exceptions`` and ``ignored_exceptions`` are provided, or a
-        numeric tunable is not a positive integer.
+        If both ``handled_exceptions`` and ``ignored_exceptions`` are provided, a
+        numeric tunable is not a positive integer, or an exception allowlist/denylist
+        is empty or contains a value that is not an exception type.
 
     Example
     -------
@@ -57,10 +65,16 @@ class CircuitBreakerConfig:
         failure_threshold: int = 5,
         recovery_timeout: int = 30,
         success_threshold: int = 3,
-        handled_exceptions: tuple[type[Exception], ...] | None = None,
-        ignored_exceptions: tuple[type[Exception], ...] | None = None,
+        handled_exceptions: type[Exception] | Iterable[type[Exception]] | None = None,
+        ignored_exceptions: type[Exception] | Iterable[type[Exception]] | None = None,
         local_cache_max_age: int = 5,
     ):
+        # Normalize first: a single exception type or any iterable becomes a tuple, and a
+        # bad value fails here (at construction) rather than as a cryptic isinstance
+        # TypeError later, the first time the circuit evaluates a failure.
+        handled_exceptions = self._normalize_exceptions(handled_exceptions, "handled_exceptions")
+        ignored_exceptions = self._normalize_exceptions(ignored_exceptions, "ignored_exceptions")
+
         self._validate(
             failure_threshold=failure_threshold,
             recovery_timeout=recovery_timeout,
@@ -105,6 +119,48 @@ class CircuitBreakerConfig:
                 f"local_cache_max_age must be a non-negative integer, got {local_cache_max_age!r}.",
             )
 
+    @classmethod
+    def _normalize_exceptions(
+        cls,
+        value: type[Exception] | Iterable[type[Exception]] | None,
+        field: str,
+    ) -> tuple[type[Exception], ...] | None:
+        """Coerce a single exception type or an iterable of them into a validated, non-empty tuple.
+
+        Runs at construction so a bad value fails immediately with a clear error, rather
+        than as a cryptic ``isinstance`` ``TypeError`` from ``counts_as_failure`` the
+        first time the circuit evaluates a failure (i.e. only once the dependency is
+        already unhealthy).
+        """
+        if value is None:
+            return None
+
+        invalid = f"{field} must be an exception type or an iterable of exception types, got {value!r}."
+        # A str is iterable; reject it rather than iterate it as a sequence of characters.
+        if isinstance(value, str):
+            raise CircuitBreakerConfigError(invalid)
+
+        if isinstance(value, type):
+            # ty (unlike mypy) does not narrow the union here, so it needs the ignore.
+            exceptions: tuple[type[Exception], ...] = (value,)  # ty: ignore[invalid-assignment]
+        else:
+            try:
+                exceptions = tuple(value)
+            except TypeError:
+                raise CircuitBreakerConfigError(invalid) from None
+
+        cls._validate_exception_types(exceptions, field)
+        return exceptions
+
+    @staticmethod
+    def _validate_exception_types(exceptions: tuple[type[Exception], ...], field: str) -> None:
+        """Require a non-empty tuple whose every element is an exception type."""
+        if not exceptions:
+            raise CircuitBreakerConfigError(f"{field} must contain at least one exception type.")
+        for exception in exceptions:
+            if not (isinstance(exception, type) and issubclass(exception, Exception)):
+                raise CircuitBreakerConfigError(f"{field} must contain only exception types, got {exception!r}.")
+
     def counts_as_failure(self, exception: Exception) -> bool:
         """
         Decide whether an exception raised by the protected call counts as a circuit failure.

{aws_lambda_powertools-3.31.0/aws_lambda_powertools/utilities/circuit_breaker_alpha → aws_lambda_powertools-3.34.0/aws_lambda_powertools/utilities/circuit_breaker}/exceptions.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from aws_lambda_powertools.utilities.circuit_breaker_alpha.states import CircuitInfo
+    from aws_lambda_powertools.utilities.circuit_breaker.states import CircuitInfo
 
 
 class CircuitBreakerError(Exception):

aws_lambda_powertools-3.34.0/aws_lambda_powertools/utilities/circuit_breaker/persistence/__init__.py

@@ -0,0 +1,15 @@
+"""
+Persistence layers for the Circuit Breaker utility.
+"""
+
+from aws_lambda_powertools.utilities.circuit_breaker.persistence.base import CircuitBreakerPersistenceLayer
+from aws_lambda_powertools.utilities.circuit_breaker.persistence.dynamodb import (
+    CircuitBreakerDynamoDBPersistence,
+)
+from aws_lambda_powertools.utilities.circuit_breaker.persistence.record import CircuitStateRecord
+
+__all__ = (
+    "CircuitBreakerPersistenceLayer",
+    "CircuitBreakerDynamoDBPersistence",
+    "CircuitStateRecord",
+)