aws-lambda-powertools 3.30.0__tar.gz → 3.31.1__tar.gz

{aws_lambda_powertools-3.30.0 → aws_lambda_powertools-3.31.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: aws_lambda_powertools
-Version: 3.30.0
+Version: 3.31.1
 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"
@@ -39,7 +39,7 @@ Requires-Dist: jsonpath-ng (>=1.6.0,<2.0.0) ; extra == "all" or extra == "datama
 Requires-Dist: protobuf (>=6.30.2,<8.0.0) ; extra == "kafka-consumer-protobuf"
 Requires-Dist: pydantic (>=2.4.0,<3.0.0) ; extra == "parser" or extra == "all"
 Requires-Dist: pydantic-settings (>=2.6.1,<3.0.0) ; extra == "all"
-Requires-Dist: redis (>=4.4,<8.0) ; extra == "redis"
+Requires-Dist: redis (>=4.4,<9.0) ; extra == "redis"
 Requires-Dist: typing-extensions (>=4.11.0,<5.0.0)
 Requires-Dist: valkey-glide (>=1.3.5,<3.0) ; extra == "valkey"
 Project-URL: Documentation, https://docs.powertools.aws.dev/lambda/python/

{aws_lambda_powertools-3.30.0 → aws_lambda_powertools-3.31.1}/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.30.0 → aws_lambda_powertools-3.31.1}/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.30.0 → aws_lambda_powertools-3.31.1}/aws_lambda_powertools/event_handler/openapi/params.py

@@ -953,54 +953,52 @@ def get_field_info_response_type(annotation, value) -> tuple[FieldInfo | None, A
     return get_field_info_and_type_annotation(inner_type, value, False, True)
 
 
-def _has_discriminator(field_info: FieldInfo) -> bool:
-    """Check if a FieldInfo has a discriminator."""
-    return hasattr(field_info, "discriminator") and field_info.discriminator is not None
-
-
-def _handle_discriminator_with_param(
+def _split_location_marker_and_field(
     annotations: list[FieldInfo],
-    annotation: Any,
-) -> tuple[FieldInfo | None, Any, bool]:
+) -> tuple[FieldInfo, FieldInfo]:
     """
-    Handle the special case of Field(discriminator) + Body() combination.
+    Split a pair of FieldInfo into the Powertools location marker and the plain Pydantic Field.
+
+    A parameter like ``Annotated[str, Field(gt=0), Query()]`` flattens to two FieldInfo: the
+    location marker (``Path``/``Query``/``Header``/``Body``, a ``Param`` or ``Body`` subclass) and
+    a plain Pydantic ``Field`` carrying constraints. We keep them apart so the location marker
+    drives where the value comes from, while the ``Field``'s constraints/metadata still apply.
 
     Returns:
-        tuple of (powertools_annotation, type_annotation, has_discriminator_with_body)
+        tuple of (location_marker, plain_field)
     """
-    field_obj = None
-    body_obj = None
+    location_marker: FieldInfo | None = None
+    plain_field: FieldInfo | None = None
 
     for ann in annotations:
-        if isinstance(ann, Body):
-            body_obj = ann
-        elif _has_discriminator(ann):
-            field_obj = ann
+        if isinstance(ann, (Param, Body)):
+            location_marker = ann
+        else:
+            plain_field = ann
 
-    if field_obj and body_obj:
-        # Use Body as the primary annotation, preserve full annotation for validation
-        return body_obj, annotation, True
+    if location_marker is None or plain_field is None:
+        raise AssertionError("Only one FieldInfo can be used per parameter")
 
-    raise AssertionError("Only one FieldInfo can be used per parameter")
+    return location_marker, plain_field
 
 
 def _create_field_info(
     powertools_annotation: FieldInfo,
     type_annotation: Any,
-    has_discriminator_with_body: bool,
+    preserve_full_annotation: bool,
 ) -> FieldInfo:
     """Create or copy FieldInfo based on the annotation type."""
-    field_info: FieldInfo
-    if has_discriminator_with_body:
-        # For discriminator + Body case, create a new Body instance directly
-        field_info = Body()
+    # Copy field_info because we mutate field_info.default later.
+    field_info = copy_field_info(
+        field_info=powertools_annotation,
+        annotation=type_annotation,
+    )
+    if preserve_full_annotation:
+        # The location marker is paired with a plain Field (constraints or discriminator).
+        # copy_field_info strips the Pydantic Field out of the metadata, so re-attach the full
+        # Annotated type here, that's what makes the Field's metadata flow into the TypeAdapter
+        # that ModelField builds for validation.
         field_info.annotation = type_annotation
-    else:
-        # Copy field_info because we mutate field_info.default later
-        field_info = copy_field_info(
-            field_info=powertools_annotation,
-            annotation=type_annotation,
-        )
     return field_info
 
 
@@ -1043,13 +1041,16 @@ def get_field_info_annotated_type(annotation, value, is_path_param: bool) -> tup
 
     # Determine which annotation to use
     powertools_annotation: FieldInfo | None = None
-    has_discriminator_with_param = False
+    # When a plain Pydantic Field is paired with a location marker (e.g. Field(gt=0) + Query),
+    # we keep the full Annotated type as the annotation so the Field's metadata still validates.
+    preserve_full_annotation = False
 
     if len(powertools_annotations) == 2:
-        powertools_annotation, type_annotation, has_discriminator_with_param = _handle_discriminator_with_param(
-            powertools_annotations,
-            annotation,
-        )
+        # A location marker (Path/Query/Header/Body) plus a plain Pydantic Field carrying
+        # constraints, a discriminator, or any other Field setting. The marker says where the
+        # value comes from; the Field says how to validate it.
+        powertools_annotation, _ = _split_location_marker_and_field(powertools_annotations)
+        preserve_full_annotation = True
     elif len(powertools_annotations) > 1:
         raise AssertionError("Only one FieldInfo can be used per parameter")
     else:
@@ -1057,18 +1058,19 @@ def get_field_info_annotated_type(annotation, value, is_path_param: bool) -> tup
 
     # Reconstruct type_annotation with non-FieldInfo metadata if present
     # This ensures constraints like Interval are preserved
-    if other_metadata and not has_discriminator_with_param:
+    if other_metadata and not preserve_full_annotation:
         type_annotation = Annotated[(type_annotation, *other_metadata)]
 
     # Process the annotation if it exists
     field_info: FieldInfo | None = None
-    if isinstance(powertools_annotation, FieldInfo):  # pragma: no cover
-        field_info = _create_field_info(powertools_annotation, type_annotation, has_discriminator_with_param)
+    if isinstance(powertools_annotation, FieldInfo):
+        # When pairing a location marker with a plain Field, hand the full Annotated[...] to the
+        # field so the Field's constraints/discriminator flow into the validating TypeAdapter.
+        field_annotation = annotation if preserve_full_annotation else type_annotation
+        field_info = _create_field_info(powertools_annotation, field_annotation, preserve_full_annotation)
         _set_field_default(field_info, value, is_path_param)
-
-        # Preserve full annotated type for discriminated unions
-        if _has_discriminator(powertools_annotation):  # pragma: no cover
-            type_annotation = annotation  # pragma: no cover
+        if preserve_full_annotation:
+            type_annotation = annotation
 
     return field_info, type_annotation
 

{aws_lambda_powertools-3.30.0 → aws_lambda_powertools-3.31.1}/aws_lambda_powertools/shared/constants.py

@@ -76,3 +76,6 @@ METADATA_DEFAULT_TIMEOUT_SECS: float = 1.0
 
 # Idempotency constants
 IDEMPOTENCY_DISABLED_ENV: str = "POWERTOOLS_IDEMPOTENCY_DISABLED"
+
+# Circuit breaker constants
+CIRCUIT_BREAKER_DISABLED_ENV: str = "POWERTOOLS_CIRCUIT_BREAKER_DISABLED"

{aws_lambda_powertools-3.30.0 → aws_lambda_powertools-3.31.1}/aws_lambda_powertools/shared/version.py

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

aws_lambda_powertools-3.31.1/aws_lambda_powertools/utilities/circuit_breaker_alpha/__init__.py

@@ -0,0 +1,35 @@
+"""
+Circuit Breaker utility for protecting unhealthy downstream dependencies.
+
+!!! warning "Alpha / experimental"
+    This utility is published under the `_alpha` namespace while we collect
+    feedback. The public API may change in a backwards-incompatible way before it
+    is promoted to GA. Pin your version and follow the tracking discussion before
+    relying on it in production.
+"""
+
+from aws_lambda_powertools.utilities.circuit_breaker_alpha.circuit_breaker import circuit_breaker
+from aws_lambda_powertools.utilities.circuit_breaker_alpha.config import CircuitBreakerConfig
+from aws_lambda_powertools.utilities.circuit_breaker_alpha.exceptions import (
+    CircuitBreakerConfigError,
+    CircuitBreakerError,
+    CircuitBreakerOpenError,
+    CircuitBreakerPersistenceError,
+)
+from aws_lambda_powertools.utilities.circuit_breaker_alpha.states import (
+    CircuitInfo,
+    CircuitState,
+    CircuitTransition,
+)
+
+__all__ = (
+    "circuit_breaker",
+    "CircuitBreakerConfig",
+    "CircuitInfo",
+    "CircuitState",
+    "CircuitTransition",
+    "CircuitBreakerError",
+    "CircuitBreakerOpenError",
+    "CircuitBreakerConfigError",
+    "CircuitBreakerPersistenceError",
+)

aws_lambda_powertools-3.31.1/aws_lambda_powertools/utilities/circuit_breaker_alpha/base.py

@@ -0,0 +1,284 @@
+"""
+Orchestrator for the Circuit Breaker utility.
+
+:class:`CircuitBreakerHandler` owns the state machine and the per-environment failure
+counter; the persistence layer owns the shared truth. This split keeps the healthy
+path write-free: failures are counted locally and only persisted on a state transition.
+"""
+
+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
+
+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 (
+        CircuitBreakerPersistenceLayer,
+    )
+    from aws_lambda_powertools.utilities.circuit_breaker_alpha.states import CircuitInfo
+
+logger = logging.getLogger(__name__)
+
+# Per-environment, per-circuit consecutive counters. Module-level so they survive across
+# invocations within the same execution environment, the same way idempotency caches do.
+_LOCAL_FAILURES: dict[str, int] = {}
+_LOCAL_SUCCESSES: dict[str, int] = {}
+
+# Tracks the last state this environment observed from the store, per circuit. Used to
+# detect transitions back to CLOSED that happened externally (another env tripped and
+# recovered), so stale local failure streaks can be invalidated.
+_LAST_OBSERVED_STATE: dict[str, CircuitState] = {}
+
+# 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:
+    """
+    Drive a single protected call through the circuit breaker state machine.
+
+    A new handler is created per invocation by the decorator. It reads the shared state,
+    routes the call (run, short-circuit, or probe), and records the outcome.
+
+    Parameters
+    ----------
+    function : Callable
+        The protected function.
+    name : str
+        Circuit name.
+    config : CircuitBreakerConfig
+        Circuit configuration.
+    persistence_store : CircuitBreakerPersistenceLayer
+        Shared state store.
+    on_circuit_open : Callable | None
+        Callback invoked with the protected call's own ``*args``/``**kwargs`` plus a
+        trailing ``circuit`` keyword argument when the circuit is open. If ``None``, an
+        open circuit raises :class:`CircuitBreakerOpenError`.
+    function_args : tuple
+        Positional arguments the protected function was called with.
+    function_kwargs : dict
+        Keyword arguments the protected function was called with.
+    """
+
+    def __init__(
+        self,
+        function: Callable,
+        name: str,
+        config: CircuitBreakerConfig,
+        persistence_store: CircuitBreakerPersistenceLayer,
+        on_circuit_open: Callable | None = None,
+        on_transition: Callable | None = None,
+        function_args: tuple | None = None,
+        function_kwargs: dict | None = None,
+    ):
+        self.function = function
+        self.name = name
+        self.config = config
+        self.on_circuit_open = on_circuit_open
+        self.on_transition = on_transition
+        self.fn_args = function_args or ()
+        self.fn_kwargs = function_kwargs or {}
+
+        persistence_store.configure(config=config, circuit_name=name)
+        self.persistence_store = persistence_store
+
+    def handle(self) -> Any:
+        """
+        Evaluate the circuit and route the call.
+
+        Returns
+        -------
+        Any
+            The protected function's result when the call runs, or the
+            ``on_circuit_open`` callback's return value when the circuit is open.
+
+        Raises
+        ------
+        CircuitBreakerOpenError
+            If the circuit is open and no callback is registered.
+        """
+        record = self.persistence_store.get_state(self.name)
+
+        if record.state == CircuitState.CLOSED:
+            # 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.
+            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:
+            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, _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 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, _probe_owner_id(), record.opened_at or 0):
+                return self._call_probe()
+
+        return self._open_response(record.to_circuit_info())
+
+    def _call_closed(self) -> Any:
+        """Run the protected call while the circuit is closed, tracking failures."""
+        try:
+            result = self.function(*self.fn_args, **self.fn_kwargs)
+        except Exception as exc:
+            if not self.config.counts_as_failure(exc):
+                raise
+            # 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(
+                    self.persistence_store.save_open,
+                    self.name,
+                    failure_count=failures,
+                    opened_at=opened_at,
+                )
+                self._notify(CircuitState.CLOSED, CircuitState.OPEN, opened_at=opened_at)
+            raise
+        else:
+            with _COUNTERS_LOCK:
+                _LOCAL_FAILURES[self.name] = 0
+            return result
+
+    def _call_probe(self) -> Any:
+        """Run a probe during half-open, closing or reopening based on the outcome."""
+        try:
+            result = self.function(*self.fn_args, **self.fn_kwargs)
+        except Exception as exc:
+            if not self.config.counts_as_failure(exc):
+                raise
+            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)
+            with _COUNTERS_LOCK:
+                _LOCAL_SUCCESSES[self.name] = 0
+            self._notify(CircuitState.HALF_OPEN, CircuitState.OPEN, opened_at=opened_at)
+            raise
+        else:
+            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)
+                self._notify(CircuitState.HALF_OPEN, CircuitState.CLOSED)
+            return result
+
+    def _safe_persist(self, fn: Callable, *args: Any, **kwargs: Any) -> None:
+        """
+        Call a persistence write, swallowing and logging failures.
+
+        State-transition writes must never mask the downstream's real result or replace
+        the downstream's real exception. This mirrors the fail-open read policy in the
+        persistence layer.
+        """
+        try:
+            fn(*args, **kwargs)
+        except Exception:
+            logger.warning(
+                "Circuit '%s': persistence write (%s) failed; the transition may be delayed but the "
+                "downstream result is preserved.",
+                self.name,
+                getattr(fn, "__name__", repr(fn)),
+                exc_info=True,
+            )
+
+    def _open_response(self, circuit: CircuitInfo) -> Any:
+        """Produce the response for an open circuit: callback result or raise."""
+        if self.on_circuit_open is not None:
+            # Forward the protected call's arguments unchanged: positional stay positional,
+            # keyword stay keyword. The circuit snapshot is passed as a keyword argument so
+            # it never collides with positionalized kwargs nor depends on dict ordering.
+            return self.on_circuit_open(*self.fn_args, **self.fn_kwargs, circuit=circuit)
+        raise CircuitBreakerOpenError(
+            f"Circuit '{self.name}' is open.",
+            circuit=circuit,
+        )
+
+    def _notify(self, from_state: CircuitState, to_state: CircuitState, opened_at: int | None = None) -> None:
+        """
+        Fire the ``on_transition`` hook for a state change.
+
+        Called only on real transitions, never on the hot path. Any exception the hook
+        raises is swallowed and logged: observability must never break the protected call.
+        """
+        if self.on_transition is None:
+            return
+        try:
+            self.on_transition(
+                CircuitTransition(
+                    circuit_name=self.name,
+                    from_state=from_state,
+                    to_state=to_state,
+                    opened_at=opened_at,
+                ),
+            )
+        except Exception:
+            logger.warning("on_transition hook for circuit '%s' raised; ignoring.", self.name, exc_info=True)
+
+    @staticmethod
+    def _now() -> int:
+        """Current unix timestamp in seconds."""
+        return int(datetime.datetime.now().timestamp())

aws_lambda_powertools-3.31.1/aws_lambda_powertools/utilities/circuit_breaker_alpha/circuit_breaker.py

@@ -0,0 +1,119 @@
+"""
+Primary interface for the Circuit Breaker utility.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import os
+import warnings
+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.warnings import PowertoolsUserWarning
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from aws_lambda_powertools.utilities.circuit_breaker_alpha.persistence.base import (
+        CircuitBreakerPersistenceLayer,
+    )
+
+logger = logging.getLogger(__name__)
+
+
+def circuit_breaker(
+    name: str,
+    persistence_store: CircuitBreakerPersistenceLayer,
+    on_circuit_open: Callable | None = None,
+    on_transition: Callable | None = None,
+    config: CircuitBreakerConfig | None = None,
+) -> Callable:
+    """
+    Protect a function that calls an unhealthy-prone downstream with a circuit breaker.
+
+    Wrap the function that makes the downstream call, not the whole Lambda handler, so a
+    tripped circuit reflects one dependency rather than unrelated handler logic.
+
+    When the circuit is open the protected function is not called. Instead, if an
+    ``on_circuit_open`` callback is registered it runs and its return value becomes the
+    call's result; otherwise :class:`CircuitBreakerOpenError` is raised.
+
+    Parameters
+    ----------
+    name : str
+        Unique circuit name. Each name is an independent circuit; a function calling
+        several backends should use one circuit per backend.
+    persistence_store : CircuitBreakerPersistenceLayer
+        Shared state store (for example ``CircuitBreakerDynamoDBPersistence``).
+    on_circuit_open : Callable | None
+        Called when the circuit is open, with the protected function's own arguments
+        (positional stay positional, keyword stay keyword) plus a trailing ``circuit``
+        keyword argument carrying a ``CircuitInfo``. Its return value becomes the call's
+        result. If ``None``, an open circuit raises ``CircuitBreakerOpenError``.
+    on_transition : Callable | None
+        Called with a single ``CircuitTransition`` argument whenever the circuit changes
+        state (open, probe, close, reopen). Fires only on transitions, never on the
+        per-invocation hot path, so it is a safe place to emit a CloudWatch metric. Any
+        exception it raises is swallowed and logged so observability never breaks the
+        protected call.
+    config : CircuitBreakerConfig | None
+        Tunables. Defaults to ``CircuitBreakerConfig()`` when omitted.
+
+    Returns
+    -------
+    Callable
+        The decorated function.
+
+    Example
+    -------
+    **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 (
+            CircuitBreakerDynamoDBPersistence,
+        )
+
+        persistence = CircuitBreakerDynamoDBPersistence(table_name="CircuitBreakerState")
+
+        def buffer(order: dict, circuit: CircuitInfo):
+            sqs.send_message(QueueUrl=url, MessageBody=json.dumps(order))
+
+        @circuit_breaker(name="payment-backend", persistence_store=persistence, on_circuit_open=buffer)
+        def charge(order: dict) -> dict:
+            return payment_api.charge(order)
+    """
+    config = config or CircuitBreakerConfig()
+
+    def decorator(function: Callable) -> Callable:
+        @functools.wraps(function)
+        def wrapper(*args, **kwargs) -> Any:
+            # Skip the circuit entirely when disabled (development only).
+            if strtobool(os.getenv(constants.CIRCUIT_BREAKER_DISABLED_ENV, "false")):
+                warnings.warn(
+                    message="Disabling the circuit breaker is intended for development environments only "
+                    "and should not be used in production.",
+                    category=PowertoolsUserWarning,
+                    stacklevel=2,
+                )
+                return function(*args, **kwargs)
+
+            handler = CircuitBreakerHandler(
+                function=function,
+                name=name,
+                config=config,
+                persistence_store=persistence_store,
+                on_circuit_open=on_circuit_open,
+                on_transition=on_transition,
+                function_args=args,
+                function_kwargs=kwargs,
+            )
+            return handler.handle()
+
+        return wrapper
+
+    return decorator