Core API¶

Import these public symbols from async_durable_execution.

Execution¶

Handler input is deserialized from the durable execution payload before user code runs. Empty or whitespace payloads are normalized to {}, and malformed JSON fails the invocation before the handler executes.

AWS Lambda Durable Executions Python SDK.

Functions:¶

durable_callable ¶

durable_callable(
    func: Callable[Params, Awaitable[T]],
) -> Callable[Params, Callable[[], Awaitable[T]]]

Wrap an async function so calling it returns a zero-argument durable callable.

The returned callable can be passed to durable operations such as step() and run_in_child_context(), keeping durable operation creation explicit while avoiding manual functools.partial(...) wrapping at the callsite.

Class and static methods are supported with either decorator order: @classmethod/@staticmethod may appear above or below @durable_callable.

durable_execution ¶

durable_execution(
    func: Callable[..., Awaitable[Any]] | None = None,
    /,
    *,
    boto3_client: LambdaApiClient
    | AsyncLambdaApiClient
    | None = None,
    service_client: DurableServiceClient | None = None,
) -> Callable[[Any, LambdaContext], Any]

Decorator to create a durable execution handler.

Parameters:

Name	Type	Description	Default
`func`	`Callable[..., Awaitable[Any]] \| None`	The user function to decorate	`None`
`boto3_client`	`LambdaApiClient \| AsyncLambdaApiClient \| None`	Optional sync or async Lambda API client to use	`None`
`service_client`	`DurableServiceClient \| None`	Optional durable service client to use. Intended for testing and local execution tooling.	`None`

Current Context¶

Use context getters only while the corresponding durable user code is running. Prefer the specific getter for the active scope: it validates the runtime context and gives type checkers the concrete context type without a cast.

Execution scope	Getter	Context type
Durable handler, child context, or parallel branch	`get_durable_context()`	`DurableContext`
Step function	`get_step_context()`	`StepContext`
Map item function	`get_map_item_context()`	`MapItemContext`
Flow node	`get_node_context()`	`FlowNodeContext`
`with_retry` body	`get_with_retry_context()`	`WithRetryContext`
`wait_for_callback` submitter	`get_wait_for_callback_context()`	`WaitForCallbackContext`
`wait_for_condition` check	`get_wait_for_condition_check_context()`	`WaitForConditionCheckContext`
Serializer or deserializer	`get_serdes_context()`	`SerDesContext`

get_current_context() remains available when code intentionally handles more than one context type.

AWS Lambda Durable Executions Python SDK.

Classes¶

DurableContext `dataclass` ¶

DurableContext(
    execution_state: ExecutionState,
    operation_identifier: OperationIdentifier,
    step_id_prefix: str | None = None,
    replaying: bool = False,
)

Bases: OperationContext

Runtime context available to a durable handler or child context.

Methods:¶

create_child_context ¶

create_child_context(
    operation_id: str,
    *,
    is_virtual: bool = False,
    replaying: bool | None = None,
) -> DurableContext

Create a child context for the given operation.

is_replaying ¶

is_replaying() -> bool

Return True while this context is replaying prior operations.

Functions:¶

get_current_context ¶

get_current_context() -> OperationContext | SerDesContext

Return the currently active durable execution context.

Raises:

Type	Description
`RuntimeError`	If called outside supported durable user code.

get_durable_context ¶

get_durable_context() -> DurableContext

Return the current context after validating durable operations are allowed.

Configuration¶

AWS Lambda Durable Executions Python SDK.

Classes¶

JitterStrategy ¶

Bases: str, Enum

Jitter strategies are used to introduce noise when attempting to retry an invoke. We introduce noise to prevent a thundering-herd effect where a group of accesses (e.g. invokes) happen at once.

Jitter is meant to be used to spread operations across time.

Based on AWS Architecture Blog: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/

members

:NONE: No jitter; use the exact calculated delay :FULL: Full jitter; random delay between 0 and calculated delay :HALF: Equal jitter; random delay between 0.5x and 1.0x of the calculated delay

Methods:¶

apply_jitter ¶

apply_jitter(delay: float) -> float

Apply jitter to a delay value and return the final delay.

Parameters:

Name	Type	Description	Default
`delay`	`float`	The base delay value to apply jitter to	required

Returns:

Type	Description
`float`	The final delay after applying jitter strategy

finalize_delay ¶

finalize_delay(base_delay: float) -> int

Apply jitter, round up, and clamp to a minimum of 1 second.

RetryStrategy `dataclass` ¶

RetryStrategy(
    max_attempts: int = 6,
    initial_delay: Duration = 5,
    max_delay: Duration = 60,
    backoff_rate: int | float = 2,
    jitter_strategy: JitterStrategy = FULL,
    increment: Duration | None = None,
    retryable_errors: list[str | Pattern] | None = None,
    retryable_error_types: list[type[Exception]]
    | None = None,
)

Bases: _DelayStrategy

Exponential-backoff retry strategy for durable operations.

Methods:¶

none `classmethod` ¶

none() -> RetryStrategy

No retries.

default `classmethod` ¶

default() -> RetryStrategy

Default retries, used automatically when no retry strategy is provided.

transient `classmethod` ¶

transient() -> RetryStrategy

Quick retries for transient errors.

resource_availability `classmethod` ¶

resource_availability() -> RetryStrategy

Longer retries for resource availability.

critical `classmethod` ¶

critical() -> RetryStrategy

Aggressive retries for critical operations.

linear `classmethod` ¶

linear() -> RetryStrategy

Linearly increasing delay between retries: 1s, 2s, 3s, 4s, 5s.

Serialization¶

AWS Lambda Durable Executions Python SDK.

Classes¶

SerDesContext `dataclass` ¶

SerDesContext(
    operation_id: str = "",
    durable_execution_arn: str = "",
    recursive_level: int = 0,
)

Context for serialization operations.

SerDes ¶

Bases: ABC, Generic[T]

Abstract serializer interface for durable operation payloads and results.

Methods:¶

serialize `abstractmethod` `async` ¶

serialize(value: T) -> str

Convert a Python value into the wire format stored by the SDK.

deserialize `abstractmethod` `async` ¶

deserialize(data: str) -> T

Reconstruct a Python value from the durable wire format.

is_primitive `staticmethod` ¶

is_primitive(obj: Any) -> bool

Check if object contains only JSON-serializable primitives.

JsonSerDes ¶

Bases: SerDes[T]

Serializer that uses the standard library json module.

ExtendedTypeSerDes ¶

ExtendedTypeSerDes(
    type_codecs: tuple[TypeCodecExtension, ...] = (),
)

Bases: SerDes[T]

Main serializer class.

Methods:¶

serialize `async` ¶

serialize(value: Any) -> str

Serialize value to JSON string.

deserialize `async` ¶

deserialize(data: str) -> Any

Deserialize JSON string to Python object.

serialize_sync ¶

serialize_sync(value: Any) -> str

Serialize value to JSON string without awaiting.

deserialize_sync ¶

deserialize_sync(data: str) -> Any

Deserialize JSON string to Python object without awaiting.

Functions:¶

get_serdes_context ¶

get_serdes_context() -> SerDesContext

Return the active SerDesContext.

Models¶

AWS Lambda Durable Executions Python SDK.

Classes¶

LambdaContext ¶

Bases: Protocol

Minimal AWS Lambda context surface used by the SDK.

OperationStatus ¶

Bases: Enum

Persisted lifecycle status of an operation in execution history.

OperationSubType ¶

Bases: Enum

Fine-grained operation kind used in execution history.

OperationType ¶

Bases: Enum

Top-level operation categories persisted by the durable backend.

InvocationStatus ¶

Bases: Enum

Overall result of a single durable Lambda invocation.

ErrorObject `dataclass` ¶

ErrorObject(
    message: str | None = None,
    type: str | None = None,
    data: str | None = None,
    stack_trace: list[str] | None = None,
)

Bases: BotoSerializableModel

Serializable representation of an exception captured by the SDK.

Exceptions¶

AWS Lambda Durable Executions Python SDK.

Classes¶

DurableExecutionsError ¶

Bases: Exception

Base class for Durable Executions exceptions

ExecutionError ¶

ExecutionError(
    message: str,
    termination_reason: TerminationReason = EXECUTION_ERROR,
)

Bases: UnrecoverableError

Error that returns FAILED status without retry.

InvocationError ¶

InvocationError(
    message: str,
    termination_reason: TerminationReason = INVOCATION_ERROR,
)

Bases: UnrecoverableError

Error that should cause Lambda retry by throwing from handler.

Methods:¶

is_retryable ¶

is_retryable() -> bool

Whether this error is retryable. Returns True by default.

Subclasses override to implement classification logic based on error codes and HTTP status codes.

build_logger_extras ¶

build_logger_extras() -> dict

Return structured logging extras for retryable invocation errors.

ValidationError ¶

Bases: DurableExecutionsError

Incorrect arguments to a Durable Function operation.

InvalidStateError ¶

Bases: DurableExecutionsError

Raised when an operation is attempted on an object in an invalid state.

UserlandError ¶

Bases: DurableExecutionsError

Failure in user-land - i.e code passed into durable executions from the caller.

CallableRuntimeError ¶

CallableRuntimeError(
    message: str | None,
    error_type: str | None,
    data: str | None,
    stack_trace: list[str] | None,
)

Bases: UserlandError

This error wraps any failure from inside the callable code that you pass to a Durable Function operation.

SerDesError ¶

Bases: DurableExecutionsError

Raised when serialization fails.

Durable Service Client¶

AWS Lambda Durable Executions Python SDK.

Classes¶

DurableServiceClient ¶

Bases: Protocol

Durable Service clients must implement this interface.

Functions:¶

create_default_sync_client ¶

create_default_sync_client() -> LambdaApiClient

Create the default botocore Lambda client used for durable API calls.

Core API¶

Execution¶

Functions:¶

durable_callable ¶

durable_execution ¶

Current Context¶

Classes¶

DurableContext dataclass ¶

Methods:¶

create_child_context ¶

is_replaying ¶

Functions:¶

get_current_context ¶

get_durable_context ¶

Configuration¶

Classes¶

JitterStrategy ¶

Methods:¶

apply_jitter ¶

finalize_delay ¶

RetryStrategy dataclass ¶

Methods:¶

none classmethod ¶

default classmethod ¶

transient classmethod ¶

resource_availability classmethod ¶

critical classmethod ¶

linear classmethod ¶

Serialization¶

Classes¶

SerDesContext dataclass ¶

SerDes ¶

Methods:¶

serialize abstractmethod async ¶

deserialize abstractmethod async ¶

is_primitive staticmethod ¶

JsonSerDes ¶

ExtendedTypeSerDes ¶

Methods:¶

serialize async ¶

deserialize async ¶

serialize_sync ¶

deserialize_sync ¶

Functions:¶

get_serdes_context ¶

Models¶

Classes¶

LambdaContext ¶

OperationStatus ¶

OperationSubType ¶

OperationType ¶

InvocationStatus ¶

ErrorObject dataclass ¶

Exceptions¶

Classes¶

DurableExecutionsError ¶

ExecutionError ¶

InvocationError ¶

Methods:¶

is_retryable ¶

build_logger_extras ¶

ValidationError ¶

InvalidStateError ¶

UserlandError ¶

CallableRuntimeError ¶

SerDesError ¶

Durable Service Client¶

Classes¶

DurableServiceClient ¶

Functions:¶

create_default_sync_client ¶

DurableContext `dataclass` ¶

RetryStrategy `dataclass` ¶

none `classmethod` ¶

default `classmethod` ¶

transient `classmethod` ¶

resource_availability `classmethod` ¶

critical `classmethod` ¶

linear `classmethod` ¶

SerDesContext `dataclass` ¶

serialize `abstractmethod` `async` ¶

deserialize `abstractmethod` `async` ¶

is_primitive `staticmethod` ¶

serialize `async` ¶

deserialize `async` ¶

ErrorObject `dataclass` ¶