aws-durable-execution-sdk-python 1.1.1__py3-none-any.whl → 1.1.2__py3-none-any.whl

aws_durable_execution_sdk_python/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Amazon.com, Inc. or its affiliates.
 #
 # SPDX-License-Identifier: Apache-2.0
-__version__ = "1.1.1"
+__version__ = "1.1.2"

aws_durable_execution_sdk_python/concurrency/executor.py

@@ -58,8 +58,9 @@ class TimerScheduler:
         self, resubmit_callback: Callable[[ExecutableWithState], None]
     ) -> None:
         self.resubmit_callback = resubmit_callback
-        self._pending_resumes: list[tuple[float, ExecutableWithState]] = []
+        self._pending_resumes: list[tuple[float, int, ExecutableWithState]] = []
         self._lock = threading.Lock()
+        self._schedule_counter = 0
         self._shutdown = threading.Event()
         self._timer_thread = threading.Thread(target=self._timer_loop, daemon=True)
         self._timer_thread.start()
@@ -73,9 +74,18 @@ class TimerScheduler:
     def schedule_resume(
         self, exe_state: ExecutableWithState, resume_time: float
     ) -> None:
-        """Schedule a task to resume at the specified time."""
+        """Schedule a task to resume at the specified time.
+
+        Uses a counter as a tie-breaker to ensure FIFO ordering when multiple
+        tasks have the same resume_time, preventing TypeError from comparing
+        ExecutableWithState objects.
+        """
         with self._lock:
-            heapq.heappush(self._pending_resumes, (resume_time, exe_state))
+            heapq.heappush(
+                self._pending_resumes,
+                (resume_time, self._schedule_counter, exe_state),
+            )
+            self._schedule_counter += 1
 
     def shutdown(self) -> None:
         """Shutdown the timer thread and cancel all pending resumes."""
@@ -108,7 +118,7 @@ class TimerScheduler:
                         self._pending_resumes
                         and self._pending_resumes[0][0] <= current_time
                     ):
-                        _, exe_state = heapq.heappop(self._pending_resumes)
+                        _, _, exe_state = heapq.heappop(self._pending_resumes)
                         if exe_state.can_resume:
                             exe_state.reset_to_pending()
                             self.resubmit_callback(exe_state)

aws_durable_execution_sdk_python/execution.py

@@ -32,7 +32,7 @@ from aws_durable_execution_sdk_python.state import ExecutionState, ReplayStatus
 if TYPE_CHECKING:
     from collections.abc import Callable, MutableMapping
 
-    import boto3  # type: ignore
+    from mypy_boto3_lambda import LambdaClient as Boto3LambdaClient
 
     from aws_durable_execution_sdk_python.types import LambdaContext
 
@@ -237,7 +237,7 @@ class DurableExecutionInvocationOutput:
 def durable_execution(
     func: Callable[[Any, DurableContext], Any] | None = None,
     *,
-    boto3_client: boto3.client | None = None,
+    boto3_client: Boto3LambdaClient | None = None,
 ) -> Callable[[Any, LambdaContext], Any]:
     # Decorator called with parameters
     if func is None:
@@ -260,7 +260,7 @@ def durable_execution(
                 logger.debug(
                     "durableExecutionArn: %s", event.get("DurableExecutionArn")
                 )
-                invocation_input = DurableExecutionInvocationInput.from_dict(event)
+                invocation_input = DurableExecutionInvocationInput.from_json_dict(event)
             except (KeyError, TypeError, AttributeError) as e:
                 msg = (
                     "Unexpected payload provided to start the durable execution. "

aws_durable_execution_sdk_python/lambda_service.py

@@ -3,12 +3,13 @@ from __future__ import annotations
 import copy
 import datetime
 import logging
+from collections.abc import MutableMapping
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Protocol, TypeAlias
+from typing import TYPE_CHECKING, Any, Protocol, TypeAlias, cast
 
-import boto3  # type: ignore
-from botocore.config import Config  # type: ignore
+import boto3
+from botocore.config import Config
 
 from aws_durable_execution_sdk_python.exceptions import (
     CallableRuntimeError,
@@ -17,7 +18,11 @@ from aws_durable_execution_sdk_python.exceptions import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import MutableMapping
+    from mypy_boto3_lambda import LambdaClient as Boto3LambdaClient
+    from mypy_boto3_lambda.type_defs import (
+        CheckpointDurableExecutionResponseTypeDef,
+        GetDurableExecutionStateResponseTypeDef,
+    )
 
     from aws_durable_execution_sdk_python.identifier import OperationIdentifier
 
@@ -1031,19 +1036,32 @@ class DurableServiceClient(Protocol):
 class LambdaClient(DurableServiceClient):
     """Persist durable operations to the Lambda Durable Function APIs."""
 
-    def __init__(self, client: Any) -> None:
+    _cached_boto_client: Boto3LambdaClient | None = None
+
+    def __init__(self, client: Boto3LambdaClient) -> None:
         self.client = client
 
-    @staticmethod
-    def initialize_client() -> LambdaClient:
-        client = boto3.client(
-            "lambda",
-            config=Config(
-                connect_timeout=5,
-                read_timeout=50,
-            ),
-        )
-        return LambdaClient(client=client)
+    @classmethod
+    def initialize_client(cls) -> LambdaClient:
+        """Initialize or return cached Lambda client.
+
+        Implements lazy initialization with class-level caching to optimize
+        Lambda warm starts. The boto3 client is created once and reused across
+        invocations, avoiding repeated credential resolution and connection
+        pool setup.
+
+        Returns:
+            LambdaClient: A new LambdaClient instance wrapping the cached boto3 client.
+        """
+        if cls._cached_boto_client is None:
+            cls._cached_boto_client = boto3.client(
+                "lambda",
+                config=Config(
+                    connect_timeout=5,
+                    read_timeout=50,
+                ),
+            )
+        return cls(client=cls._cached_boto_client)
 
     def checkpoint(
         self,
@@ -1053,19 +1071,20 @@ class LambdaClient(DurableServiceClient):
         client_token: str | None,
     ) -> CheckpointOutput:
         try:
-            params = {
-                "DurableExecutionArn": durable_execution_arn,
-                "CheckpointToken": checkpoint_token,
-                "Updates": [o.to_dict() for o in updates],
-            }
+            optional_params: dict[str, str] = {}
             if client_token is not None:
-                params["ClientToken"] = client_token
-
-            result: MutableMapping[str, Any] = self.client.checkpoint_durable_execution(
-                **params
+                optional_params["ClientToken"] = client_token
+
+            result: CheckpointDurableExecutionResponseTypeDef = (
+                self.client.checkpoint_durable_execution(
+                    DurableExecutionArn=durable_execution_arn,
+                    CheckpointToken=checkpoint_token,
+                    Updates=cast(Any, [o.to_dict() for o in updates]),
+                    **optional_params,  # type: ignore[arg-type]
+                )
             )
 
-            return CheckpointOutput.from_dict(result)
+            return CheckpointOutput.from_dict(cast(MutableMapping[str, Any], result))
         except Exception as e:
             checkpoint_error = CheckpointError.from_exception(e)
             logger.exception(
@@ -1081,13 +1100,15 @@ class LambdaClient(DurableServiceClient):
         max_items: int = 1000,
     ) -> StateOutput:
         try:
-            result: MutableMapping[str, Any] = self.client.get_durable_execution_state(
-                DurableExecutionArn=durable_execution_arn,
-                CheckpointToken=checkpoint_token,
-                Marker=next_marker,
-                MaxItems=max_items,
+            result: GetDurableExecutionStateResponseTypeDef = (
+                self.client.get_durable_execution_state(
+                    DurableExecutionArn=durable_execution_arn,
+                    CheckpointToken=checkpoint_token,
+                    Marker=next_marker,
+                    MaxItems=max_items,
+                )
             )
-            return StateOutput.from_dict(result)
+            return StateOutput.from_dict(cast(MutableMapping[str, Any], result))
         except Exception as e:
             error = GetExecutionStateError.from_exception(e)
             logger.exception(

aws_durable_execution_sdk_python/state.py

@@ -314,6 +314,7 @@ class ExecutionState:
                         OperationStatus.FAILED,
                         OperationStatus.CANCELLED,
                         OperationStatus.STOPPED,
+                        OperationStatus.TIMED_OUT,
                     }
                 }
                 if completed_ops.issubset(self._visited_operations):

aws_durable_execution_sdk_python-1.1.2.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: aws-durable-execution-sdk-python
+Version: 1.1.2
+Summary: AWS Durable Execution SDK for Python
+Project-URL: Documentation, https://github.com/aws/aws-durable-execution-sdk-python#readme
+Project-URL: Issues, https://github.com/aws/aws-durable-execution-sdk-python/issues
+Project-URL: Source, https://github.com/aws/aws-durable-execution-sdk-python
+Author-email: yaythomas <tgaigher@amazon.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.42.1
+Description-Content-Type: text/markdown
+
+# AWS Durable Execution SDK for Python
+
+[![Build](https://github.com/aws/aws-durable-execution-sdk-python/actions/workflows/ci.yml/badge.svg)](https://github.com/aws/aws-durable-execution-sdk-python/actions/workflows/ci.yml)
+[![PyPI - Version](https://img.shields.io/pypi/v/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/aws/aws-durable-execution-sdk-python/badge)](https://scorecard.dev/viewer/?uri=github.com/aws/aws-durable-execution-sdk-python)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+
+-----
+
+Build reliable, long-running AWS Lambda workflows with checkpointed steps, waits, callbacks, and parallel execution.
+
+## ✨ Key Features
+
+- **Automatic checkpointing** - Resume execution after Lambda pauses or restarts
+- **Durable steps** - Run work with retry strategies and deterministic replay
+- **Waits and callbacks** - Pause for time or external signals without blocking Lambda
+- **Parallel and map operations** - Fan out work with configurable completion criteria
+- **Child contexts** - Structure complex workflows into isolated subflows
+- **Replay-safe logging** - Use `context.logger` for structured, de-duplicated logs
+- **Local and cloud testing** - Validate workflows with the testing SDK
+
+## 📦 Packages
+
+| Package | Description | Version |
+| --- | --- | --- |
+| `aws-durable-execution-sdk-python` | Execution SDK for Lambda durable functions | [![PyPI - Version](https://img.shields.io/pypi/v/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python) |
+| `aws-durable-execution-sdk-python-testing` | Local/cloud test runner and pytest helpers | [![PyPI - Version](https://img.shields.io/pypi/v/aws-durable-execution-sdk-python-testing.svg)](https://pypi.org/project/aws-durable-execution-sdk-python-testing) |
+
+## 🚀 Quick Start
+
+Install the execution SDK:
+
+```console
+pip install aws-durable-execution-sdk-python
+```
+
+Create a durable Lambda handler:
+
+```python
+from aws_durable_execution_sdk_python import (
+    DurableContext,
+    StepContext,
+    durable_execution,
+    durable_step,
+)
+from aws_durable_execution_sdk_python.config import Duration
+
+@durable_step
+def validate_order(step_ctx: StepContext, order_id: str) -> dict:
+    step_ctx.logger.info("Validating order", extra={"order_id": order_id})
+    return {"order_id": order_id, "valid": True}
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> dict:
+    order_id = event["order_id"]
+    context.logger.info("Starting workflow", extra={"order_id": order_id})
+
+    validation = context.step(validate_order(order_id), name="validate_order")
+    if not validation["valid"]:
+        return {"status": "rejected", "order_id": order_id}
+
+    # simulate approval (real world: use wait_for_callback)
+    context.wait(duration=Duration.from_seconds(5), name="await_confirmation")
+
+    return {"status": "approved", "order_id": order_id}
+```
+
+## 📚 Documentation
+
+- **[AWS Documentation](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html)** - Official AWS Lambda durable functions guide
+- **[Documentation index](docs/index.md)** - SDK Overview and navigation
+
+**New to durable functions?**
+- [Getting started guide](docs/getting-started.md) - Build your first durable function
+
+**Core operations:**
+- [Steps](docs/core/steps.md) - Execute code with automatic checkpointing and retry support
+- [Wait operations](docs/core/wait.md) - Pause execution without blocking Lambda resources
+- [Callbacks](docs/core/callbacks.md) - Wait for external systems to respond
+- [Invoke operations](docs/core/invoke.md) - Call other durable functions and compose workflows
+- [Child contexts](docs/core/child-contexts.md) - Organize complex workflows into isolated units
+- [Parallel operations](docs/core/parallel.md) - Run multiple operations concurrently
+- [Map operations](docs/core/map.md) - Process collections in parallel with batching
+- [Logger integration](docs/core/logger.md) - Add structured logging to track execution
+
+**Advanced topics:**
+- [Error handling](docs/advanced/error-handling.md) - Handle failures and implement retry strategies
+- [Testing modes](docs/advanced/testing-modes.md) - Run tests locally or against deployed Lambda functions
+- [Testing patterns](docs/testing-patterns/basic-tests.md) - Practical testing examples
+- [Serialization](docs/advanced/serialization.md) - Customize how data is serialized in checkpoints
+
+**Architecture:**
+- [Architecture diagrams](docs/architecture.md) - Class diagrams and concurrency flows
+
+**API reference:**
+- API reference docs are in progress. Use the core operation docs above for now.
+
+## 💬 Feedback & Support
+
+- [Bug report](https://github.com/aws/aws-durable-execution-sdk-python/issues/new?template=bug_report.yml)
+- [Feature request](https://github.com/aws/aws-durable-execution-sdk-python/issues/new?template=feature_request.yml)
+- [Documentation feedback](https://github.com/aws/aws-durable-execution-sdk-python/issues/new?template=documentation.yml)
+- [Contributing guide](CONTRIBUTING.md)
+
+## 📄 License
+
+See the [LICENSE](LICENSE) file for our project's licensing.

{aws_durable_execution_sdk_python-1.1.1.dist-info → aws_durable_execution_sdk_python-1.1.2.dist-info}/RECORD

@@ -1,23 +1,23 @@
 aws_durable_execution_sdk_python/.gitignore,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-aws_durable_execution_sdk_python/__about__.py,sha256=K6F0cNJyiPOnBo1OtQh0Zl8-xoMS7hubOJU6p2XfWG0,137
+aws_durable_execution_sdk_python/__about__.py,sha256=7qzc63t8OUhHP9YvXrUIRIK7LxcEvXL60VN7Z4b_y4M,137
 aws_durable_execution_sdk_python/__init__.py,sha256=reI6AQTpEyeK3ev6iZJuu7A6PSoa0V1VJGOgSB2RpGM,1023
 aws_durable_execution_sdk_python/config.py,sha256=vd_8IZO5KZU3qWENbWDVtyLglqw3sa6SU-R8CYUgm9g,18938
 aws_durable_execution_sdk_python/context.py,sha256=efJIc5KrsTzcI_azMjxqrHiPt71PuiQy4vbdsUiTtLI,22467
 aws_durable_execution_sdk_python/exceptions.py,sha256=AvuXnBHAijXb3TepNTu5CVDb_cpR6Yw6x4W3jELVneQ,13631
-aws_durable_execution_sdk_python/execution.py,sha256=JNlSKsMr_GHw2ky75mZl68NgUu0QHrlX3JDN7-vwRxA,18526
+aws_durable_execution_sdk_python/execution.py,sha256=A20fOp6_wXdIcL1YiqJ_RGJbQ09D1lSivBQnUY0FT3Y,18571
 aws_durable_execution_sdk_python/identifier.py,sha256=0NyNTb8mTrUni7PlmFtzvJdW6lk0_XpuAaL89LNc378,324
-aws_durable_execution_sdk_python/lambda_service.py,sha256=2qrufd2SSFxOmeGnXC-PKoAh8ASsNxKSpqBsFwthRZE,36814
+aws_durable_execution_sdk_python/lambda_service.py,sha256=FkkcmFxDZLA4JS7mMW2YT9BfqTNHHJtEk9kSADwu5bk,37858
 aws_durable_execution_sdk_python/logger.py,sha256=nde1fhe9uK-UmXRZI7T_sIoU-_T5PnZo16boaFQFtyw,4281
 aws_durable_execution_sdk_python/py.typed,sha256=DbCDcAirv769HS1ibzZLXq8VPazYf7JCkKSzj3ctudM,58
 aws_durable_execution_sdk_python/retries.py,sha256=CNJ6msQHVhcdSjMuuQAvR0WvsaN7cFA7QgQTVI8pK2w,5829
 aws_durable_execution_sdk_python/serdes.py,sha256=-hzqPyAHi1rsOUwpi7RjiJBNiDc0Oe5_QVNMemYBfGY,16808
-aws_durable_execution_sdk_python/state.py,sha256=Gd3Q-6wViggkBxPeGHd0gd3jh8IDtT3TTiQZuKH7YqU,33252
+aws_durable_execution_sdk_python/state.py,sha256=5kWSwtOCt0VkhhB2orhGyrXNg1nBt-HXfXm0T8VzAiE,33303
 aws_durable_execution_sdk_python/suspend.py,sha256=PIgc6w5-diZIq58-tPv51dzBSHGW7e4oR0QFam8Vgi0,3323
 aws_durable_execution_sdk_python/threading.py,sha256=cU7vIEWHYco-qqkgoAMyPHSOQ8b_Q_r_rZGG7m1g7I4,7650
 aws_durable_execution_sdk_python/types.py,sha256=8vqwa5q2EikesX_NdhR_njin7l7uHakhWPH_ntHY_PI,5152
 aws_durable_execution_sdk_python/waits.py,sha256=ZO_SWafI0G7rWxItpnL7w4o--eDp2VAjnGZlrBJfufc,3883
 aws_durable_execution_sdk_python/concurrency/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-aws_durable_execution_sdk_python/concurrency/executor.py,sha256=LqGGDE94My7ECsaOcvfZE_-yZmYVXM0Um9M0_Z042rI,17800
+aws_durable_execution_sdk_python/concurrency/executor.py,sha256=NkpB0gRRykhc1eMB1xGNy7VPMawIkejMuV2-T--Vnao,18156
 aws_durable_execution_sdk_python/concurrency/models.py,sha256=wPi0PEFsCFthoXlRMkomS0Tl9hZ7IVk4d-9xWH5cIJQ,15540
 aws_durable_execution_sdk_python/operation/__init__.py,sha256=xjtSpukZb6sftgJ5oVPSc6TcgKgVQg4vXHeYIeKOPks,25
 aws_durable_execution_sdk_python/operation/base.py,sha256=5Ppis4xFJoXQK4f7-cF-RYmeF84nAVlepzJgHx_OBYc,7049
@@ -29,8 +29,8 @@ aws_durable_execution_sdk_python/operation/parallel.py,sha256=uzxa_XsTvimC63Hpad
 aws_durable_execution_sdk_python/operation/step.py,sha256=5R-Rzmfh5uYHMQdq3WoDzwXUBwNg-ToeWW5DI7_l7zw,15567
 aws_durable_execution_sdk_python/operation/wait.py,sha256=P1R7-BrQ0eadFxQiGLHL3ySkuJUqPvVv7zewAzBeVT8,4193
 aws_durable_execution_sdk_python/operation/wait_for_condition.py,sha256=s33dEf5qosed_DxZiNN0A_t9DHfpHBpcfD7HqaEfbx0,11768
-aws_durable_execution_sdk_python-1.1.1.dist-info/METADATA,sha256=QSBZSwoHHCatVYvyiixMZ2dbMXwrBO9iVS-QcJGvb7U,23580
-aws_durable_execution_sdk_python-1.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-aws_durable_execution_sdk_python-1.1.1.dist-info/licenses/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
-aws_durable_execution_sdk_python-1.1.1.dist-info/licenses/NOTICE,sha256=1CkO1kwu3Q_OHYTj-d-yiBJA_lNN73a4zSntavaD4oc,67
-aws_durable_execution_sdk_python-1.1.1.dist-info/RECORD,,
+aws_durable_execution_sdk_python-1.1.2.dist-info/METADATA,sha256=hYagEtD3Dl8MjSAH41gPAODHtYKb3Dyo3CNpm4mA9xs,6424
+aws_durable_execution_sdk_python-1.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+aws_durable_execution_sdk_python-1.1.2.dist-info/licenses/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
+aws_durable_execution_sdk_python-1.1.2.dist-info/licenses/NOTICE,sha256=1CkO1kwu3Q_OHYTj-d-yiBJA_lNN73a4zSntavaD4oc,67
+aws_durable_execution_sdk_python-1.1.2.dist-info/RECORD,,

aws_durable_execution_sdk_python-1.1.1.dist-info/METADATA

@@ -1,681 +0,0 @@
-Metadata-Version: 2.4
-Name: aws-durable-execution-sdk-python
-Version: 1.1.1
-Summary: AWS Durable Execution SDK for Python
-Project-URL: Documentation, https://github.com/aws/aws-durable-execution-sdk-python#readme
-Project-URL: Issues, https://github.com/aws/aws-durable-execution-sdk-python/issues
-Project-URL: Source, https://github.com/aws/aws-durable-execution-sdk-python
-Author-email: yaythomas <tgaigher@amazon.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Python: >=3.11
-Requires-Dist: boto3>=1.42.1
-Description-Content-Type: text/markdown
-
-# AWS Durable Execution SDK for Python
-
-[![PyPI - Version](https://img.shields.io/pypi/v/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python)
-
-[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/aws/aws-durable-execution-sdk-python/badge)](https://scorecard.dev/viewer/?uri=github.com/aws/aws-durable-execution-sdk-python)
-
------
-
-## Table of Contents
-
-- [Installation](#installation)
-- [License](#license)
-
-## Installation
-
-```console
-pip install aws-durable-execution-sdk-python
-```
-
-## Developers
-Please see [CONTRIBUTING.md](CONTRIBUTING.md). It contains the testing guide, sample commands and instructions
-for how to contribute to this package.
-
-tldr; use `hatch` and it will manage virtual envs and dependencies for you, so you don't have to do it manually.
-
-## Core Architecture
-The entry-point that consumers of the SDK interact with is the DurableContext.
-
-### DurableContext Operations
-- **Core Methods**: `set_logger`, `step`, `invoke`, `map`, `parallel`, `run_in_child_context`, `wait`, `create_callback`, `wait_for_callback`, `wait_for_condition`
-- **Thread Safety**: Uses `OrderedCounter` for generating sequential step IDs
-- **State Management**: Delegates to `ExecutionState` for checkpointing
-
-### Concurrency Implementation
-- **Map/Parallel**: Both inherit from `ConcurrentExecutor` abstract base class
-- **Thread Pool**: Uses `ThreadPoolExecutor` for concurrent execution
-- **State Tracking**: `ExecutableWithState` manages individual task lifecycle
-- **Completion Logic**: `ExecutionCounters` tracks success/failure criteria
-- **Suspension**: `TimerScheduler` handles timed suspensions and resumptions
-
-### Configuration System
-- **Modular Configs**: Separate config classes for each operation type
-- **Completion Control**: `CompletionConfig` defines success/failure criteria
-- **Serialization**: `SerDes` interface for custom serialization
-
-### Operation Handlers
-- **Separation of Concerns**: Each operation has dedicated handler function
-- **Checkpointing**: All operations integrate with execution state checkpointing
-- **Error Handling**: Consistent error handling and retry logic across operations
-
-
-```mermaid
-classDiagram
-    class DurableContext {
-        -ExecutionState state
-        -Any lambda_context
-        -str _parent_id
-        -OrderedCounter _step_counter
-        -LogInfo _log_info
-        -Logger logger
-        
-        +set_logger(LoggerInterface new_logger)
-        +step(Callable func, str name, StepConfig config) T
-        +invoke(str function_name, P payload, str name, InvokeConfig config) R
-        +map(Sequence inputs, Callable func, str name, MapConfig config) BatchResult
-        +parallel(Sequence functions, str name, ParallelConfig config) BatchResult
-        +run_in_child_context(Callable func, str name, ChildConfig config) T
-        +wait(int seconds, str name)
-        +create_callback(str name, CallbackConfig config) Callback
-        +wait_for_callback(Callable submitter, str name, WaitForCallbackConfig config) Any
-        +wait_for_condition(Callable check, WaitForConditionConfig config, str name) T
-    }
-
-    class DurableContextProtocol {
-        <<interface>>
-        +step(Callable func, str name, StepConfig config) T
-        +run_in_child_context(Callable func, str name, ChildConfig config) T
-        +map(Sequence inputs, Callable func, str name, MapConfig config) BatchResult
-        +parallel(Sequence functions, str name, ParallelConfig config) BatchResult
-        +wait(int seconds, str name)
-        +create_callback(str name, CallbackConfig config) Callback
-    }
-
-    class OrderedCounter {
-        -OrderedLock _lock
-        -int _counter
-        +increment() int
-        +decrement() int
-        +get_current() int
-    }
-
-    class ExecutionState {
-        +str durable_execution_arn
-        +get_checkpoint_result(str operation_id) CheckpointedResult
-        +create_checkpoint(OperationUpdate operation_update)
-    }
-
-    class Logger {
-        +LoggerInterface logger
-        +LogInfo info
-        +with_log_info(LogInfo info) Logger
-        +from_log_info(LoggerInterface logger, LogInfo info) Logger
-    }
-
-    DurableContext ..|> DurableContextProtocol : implements
-    DurableContext --> ExecutionState : uses
-    DurableContext --> OrderedCounter : contains
-    DurableContext --> Logger : contains
-```
-
-## Operation Handlers
-The `DurableContext` calls operation handlers, which contain the execution logic for each operation.
-
-```mermaid
-classDiagram
-    class DurableContext {
-        +step(Callable func, str name, StepConfig config) T
-        +invoke(str function_name, P payload, str name, InvokeConfig config) R
-        +map(Sequence inputs, Callable func, str name, MapConfig config) BatchResult
-        +parallel(Sequence functions, str name, ParallelConfig config) BatchResult
-        +run_in_child_context(Callable func, str name, ChildConfig config) T
-        +wait(int seconds, str name)
-        +create_callback(str name, CallbackConfig config) Callback
-        +wait_for_callback(Callable submitter, str name, WaitForCallbackConfig config) Any
-        +wait_for_condition(Callable check, WaitForConditionConfig config, str name) T
-    }
-
-    class step_handler {
-        <<function>>
-        +step_handler(Callable func, ExecutionState state, OperationIdentifier op_id, StepConfig config, Logger logger) T
-    }
-
-    class invoke_handler {
-        <<function>>
-        +invoke_handler(str function_name, P payload, ExecutionState state, OperationIdentifier op_id, InvokeConfig config) R
-    }
-
-    class map_handler {
-        <<function>>
-        +map_handler(Sequence items, Callable func, MapConfig config, ExecutionState state, Callable run_in_child_context) BatchResult
-    }
-
-    class parallel_handler {
-        <<function>>
-        +parallel_handler(Sequence callables, ParallelConfig config, ExecutionState state, Callable run_in_child_context) BatchResult
-    }
-
-    class child_handler {
-        <<function>>
-        +child_handler(Callable func, ExecutionState state, OperationIdentifier op_id, ChildConfig config) T
-    }
-
-    class wait_handler {
-        <<function>>
-        +wait_handler(int seconds, ExecutionState state, OperationIdentifier op_id)
-    }
-
-    class create_callback_handler {
-        <<function>>
-        +create_callback_handler(ExecutionState state, OperationIdentifier op_id, CallbackConfig config) str
-    }
-
-    class wait_for_callback_handler {
-        <<function>>
-        +wait_for_callback_handler(DurableContext context, Callable submitter, str name, WaitForCallbackConfig config) Any
-    }
-
-    class wait_for_condition_handler {
-        <<function>>
-        +wait_for_condition_handler(Callable check, WaitForConditionConfig config, ExecutionState state, OperationIdentifier op_id, Logger logger) T
-    }
-
-    DurableContext --> step_handler : calls
-    DurableContext --> invoke_handler : calls
-    DurableContext --> map_handler : calls
-    DurableContext --> parallel_handler : calls
-    DurableContext --> child_handler : calls
-    DurableContext --> wait_handler : calls
-    DurableContext --> create_callback_handler : calls
-    DurableContext --> wait_for_callback_handler : calls
-    DurableContext --> wait_for_condition_handler : calls
-```
-
-## Configuration Module Classes
-
-```mermaid
-classDiagram
-    class StepConfig {
-        +Callable retry_strategy
-        +StepSemantics step_semantics
-        +SerDes serdes
-    }
-
-    class InvokeConfig~P,R~ {
-        +int timeout_seconds
-        +SerDes~P~ serdes_payload
-        +SerDes~R~ serdes_result
-    }
-
-    class MapConfig {
-        +int max_concurrency
-        +ItemBatcher item_batcher
-        +CompletionConfig completion_config
-        +SerDes serdes
-    }
-
-    class ParallelConfig {
-        +int max_concurrency
-        +CompletionConfig completion_config
-        +SerDes serdes
-    }
-
-    class ChildConfig~T~ {
-        +SerDes serdes
-        +OperationSubType sub_type
-        +Callable~T,str~ summary_generator
-    }
-
-    class CallbackConfig {
-        +int timeout_seconds
-        +int heartbeat_timeout_seconds
-        +SerDes serdes
-    }
-
-    class WaitForCallbackConfig {
-        +Callable retry_strategy
-    }
-
-    class WaitForConditionConfig~T~ {
-        +Callable wait_strategy
-        +T initial_state
-        +SerDes serdes
-    }
-
-    class CompletionConfig {
-        +int min_successful
-        +int tolerated_failure_count
-        +float tolerated_failure_percentage
-        +first_successful()$ CompletionConfig
-        +all_completed()$ CompletionConfig
-        +all_successful()$ CompletionConfig
-    }
-
-    class ItemBatcher~T~ {
-        +int max_items_per_batch
-        +float max_item_bytes_per_batch
-        +T batch_input
-    }
-
-    WaitForCallbackConfig --|> CallbackConfig : extends
-    MapConfig --> CompletionConfig : contains
-    MapConfig --> ItemBatcher : contains
-    ParallelConfig --> CompletionConfig : contains
-```
-
-## Types and Protocols Module
-
-```mermaid
-classDiagram
-    class DurableContextProtocol {
-        <<interface>>
-        +step(Callable func, str name, StepConfig config) T
-        +run_in_child_context(Callable func, str name, ChildConfig config) T
-        +map(Sequence inputs, Callable func, str name, MapConfig config) BatchResult
-        +parallel(Sequence functions, str name, ParallelConfig config) BatchResult
-        +wait(int seconds, str name)
-        +create_callback(str name, CallbackConfig config) Callback
-    }
-
-    class LoggerInterface {
-        <<interface>>
-        +debug(object msg, *args, Mapping extra)
-        +info(object msg, *args, Mapping extra)
-        +warning(object msg, *args, Mapping extra)
-        +error(object msg, *args, Mapping extra)
-        +exception(object msg, *args, Mapping extra)
-    }
-
-    class CallbackProtocol~C_co~ {
-        <<interface>>
-        +str callback_id
-        +result() C_co
-    }
-
-    class BatchResultProtocol~T~ {
-        <<interface>>
-        +get_results() list~T~
-    }
-
-    class StepContext {
-        +LoggerInterface logger
-    }
-
-    class WaitForConditionCheckContext {
-        +LoggerInterface logger
-    }
-
-    class OperationContext {
-        +LoggerInterface logger
-    }
-
-    StepContext --|> OperationContext : extends
-    WaitForConditionCheckContext --|> OperationContext : extends
-```
-
-## SerDes Module Classes
-
-```mermaid
-classDiagram
-    class SerDes~T~ {
-        <<abstract>>
-        +serialize(T value, SerDesContext context) str
-        +deserialize(str data, SerDesContext context) T
-    }
-
-    class JsonSerDes~T~ {
-        +serialize(T value, SerDesContext context) str
-        +deserialize(str data, SerDesContext context) T
-    }
-
-    class SerDesContext {
-        +str operation_id
-        +str durable_execution_arn
-    }
-
-    class serialize {
-        <<function>>
-        +serialize(SerDes serdes, T value, str operation_id, str durable_execution_arn) str
-    }
-
-    class deserialize {
-        <<function>>
-        +deserialize(SerDes serdes, str data, str operation_id, str durable_execution_arn) T
-    }
-
-    JsonSerDes ..|> SerDes : implements
-    serialize --> SerDes : uses
-    deserialize --> SerDes : uses
-    SerDes --> SerDesContext : uses
-```
-
-## Concurrency Architecture - Map and Parallel Operations
-
-```mermaid
-classDiagram
-    class ConcurrentExecutor~CallableType,ResultType~ {
-        <<abstract>>
-        +list~Executable~ executables
-        +int max_concurrency
-        +CompletionConfig completion_config
-        +ExecutionCounters counters
-        +list~ExecutableWithState~ executables_with_state
-        +Event _completion_event
-        +SuspendExecution _suspend_exception
-        
-        +execute(ExecutionState state, Callable run_in_child_context) BatchResult~ResultType~
-        +execute_item(DurableContext child_context, Executable executable)* ResultType
-        +should_execution_suspend() SuspendResult
-        -_on_task_complete(ExecutableWithState exe_state, Future future, TimerScheduler scheduler)
-        -_create_result() BatchResult~ResultType~
-    }
-
-    class MapExecutor~T,R~ {
-        +Sequence~T~ items
-        +execute_item(DurableContext child_context, Executable executable) R
-        +from_items(Sequence items, Callable func, MapConfig config)$ MapExecutor
-    }
-
-    class ParallelExecutor {
-        +execute_item(DurableContext child_context, Executable executable) R
-        +from_callables(Sequence callables, ParallelConfig config)$ ParallelExecutor
-    }
-
-    class Executable~CallableType~ {
-        +int index
-        +CallableType func
-    }
-
-    class ExecutableWithState~CallableType,ResultType~ {
-        +Executable~CallableType~ executable
-        -BranchStatus _status
-        -Future _future
-        -float _suspend_until
-        -ResultType _result
-        -Exception _error
-        
-        +run(Future future)
-        +suspend()
-        +suspend_with_timeout(float timestamp)
-        +complete(ResultType result)
-        +fail(Exception error)
-        +reset_to_pending()
-        +can_resume() bool
-        +is_running() bool
-    }
-
-    class ExecutionCounters {
-        +int total_tasks
-        +int min_successful
-        +int success_count
-        +int failure_count
-        -Lock _lock
-        
-        +complete_task()
-        +fail_task()
-        +should_complete() bool
-        +is_all_completed() bool
-        +is_min_successful_reached() bool
-        +is_failure_tolerance_exceeded() bool
-    }
-
-    class TimerScheduler {
-        +Callable resubmit_callback
-        -list _pending_resumes
-        -Lock _lock
-        -Event _shutdown
-        -Thread _timer_thread
-        
-        +schedule_resume(ExecutableWithState exe_state, float resume_time)
-        +shutdown()
-        -_timer_loop()
-    }
-
-    class BatchResult~R~ {
-        +list~BatchItem~R~~ all
-        +CompletionReason completion_reason
-        +succeeded() list~BatchItem~R~~
-        +failed() list~BatchItem~R~~
-        +get_results() list~R~
-        +throw_if_error()
-    }
-
-    class BatchItem~R~ {
-        +int index
-        +BatchItemStatus status
-        +R result
-        +ErrorObject error
-    }
-
-    MapExecutor --|> ConcurrentExecutor : extends
-    ParallelExecutor --|> ConcurrentExecutor : extends
-    ConcurrentExecutor --> ExecutableWithState : manages
-    ConcurrentExecutor --> ExecutionCounters : uses
-    ConcurrentExecutor --> TimerScheduler : uses
-    ConcurrentExecutor --> BatchResult : creates
-    ExecutableWithState --> Executable : contains
-    BatchResult --> BatchItem : contains
-```
-
-## Concurrency Flow
-
-```mermaid
-sequenceDiagram
-    participant DC as DurableContext
-    participant MH as map_handler
-    participant ME as MapExecutor
-    participant CE as ConcurrentExecutor
-    participant TP as ThreadPoolExecutor
-    participant TS as TimerScheduler
-    participant EC as ExecutionCounters
-
-    DC->>MH: map(inputs, func, config)
-    MH->>ME: MapExecutor.from_items()
-    ME->>CE: execute(state, run_in_child_context)
-    
-    CE->>TP: ThreadPoolExecutor(max_workers)
-    CE->>TS: TimerScheduler(resubmitter)
-    CE->>EC: ExecutionCounters(total, min_successful)
-    
-    loop For each executable
-        CE->>TP: submit_task(executable_with_state)
-        TP->>CE: execute_item_in_child_context()
-        CE->>DC: run_in_child_context(child_func)
-        DC->>ME: execute_item(child_context, executable)
-    end
-    
-    par Task Completion Handling
-        TP->>CE: on_task_complete(future)
-        CE->>EC: complete_task() / fail_task()
-        CE->>CE: should_execution_suspend()
-        alt Should Complete
-            CE->>CE: _completion_event.set()
-        else Should Suspend
-            CE->>TS: schedule_resume(exe_state, timestamp)
-        end
-    end
-    
-    CE->>CE: _completion_event.wait()
-    CE->>CE: _create_result()
-    CE->>DC: BatchResult
-```
-
-## Threading and Locking
-
-```mermaid
-classDiagram
-    class OrderedLock {
-        -Lock _lock
-        -deque~Event~ _waiters
-        -bool _is_broken
-        -Exception _exception
-        
-        +acquire() bool
-        +release()
-        +reset()
-        +is_broken() bool
-        +__enter__() OrderedLock
-        +__exit__(exc_type, exc_val, exc_tb)
-    }
-
-    class OrderedCounter {
-        -OrderedLock _lock
-        -int _counter
-        
-        +increment() int
-        +decrement() int
-        +get_current() int
-    }
-
-    class Event {
-        <<threading.Event>>
-        +set()
-        +wait()
-    }
-
-    class Lock {
-        <<threading.Lock>>
-        +acquire()
-        +release()
-    }
-
-    OrderedCounter --> OrderedLock : uses
-    OrderedLock --> Lock : contains
-    OrderedLock --> Event : manages queue of
-```
-
-## Checkpointing System
-
-The SDK invokes the AWS Lambda checkpoint API to persist execution state. Checkpoints are batched for efficiency and can be either 
-synchronous (blocking) or asynchronous (non-blocking). Critical checkpoints are blocking,
-meaning that execution will not proceed until the checkpoint call has successfully completed.
-
-### Checkpoint Types
-
-Checkpoints are categorized by their action (START, SUCCEED, FAIL) and whether they are critical to execution correctness:
-
-| Operation Type | Action | Is Sync? | Rationale |
-|---------------|--------|----------|-----------|
-| Step (AtMostOncePerRetry) | START | Yes | Prevents duplicate execution - must wait for confirmation |
-| Step (AtLeastOncePerRetry) | START | No | Performance optimization - idempotent operations can retry |
-| Step | SUCCEED/FAIL | Yes | Ensures result persisted before returning to caller |
-| Callback | START | Yes | Must wait for API to generate callback ID |
-| Callback | SUCCEED/FAIL | Yes | Ensures callback result persisted |
-| Invoke | START | Yes | Ensures chained invoke recorded before proceeding |
-| Invoke | SUCCEED/FAIL | Yes | Ensures invoke result persisted |
-| Context (Child) | START | No | Fire-and-forget for performance - parent tracks completion |
-| Context (Child) | SUCCEED/FAIL | Yes | Ensures child result available to parent |
-| Wait | START | No | Observability only - no blocking needed |
-| Wait | SUCCEED | Yes | Ensures wait completion recorded |
-| Wait for Condition | START | No | Observability only - condition check is idempotent |
-| Wait for Condition | SUCCEED/FAIL | Yes | Ensures condition result persisted |
-| Empty Checkpoint | N/A | Yes (default) | Refreshes checkpoint token and operations list |
-
-### Synchronous vs Asynchronous Checkpoints
-
-**Synchronous Checkpoints (is_sync=True, default)**:
-- Block the caller until the checkpoint is processed by the background thread
-- Ensure the checkpoint is persisted before continuing execution
-- Safe default for correctness
-- Used for critical operations where confirmation is required
-
-**Asynchronous Checkpoints (is_sync=False, opt-in)**:
-- Return immediately without waiting for the checkpoint to complete
-- Performance optimization for specific use cases
-- Used for observability checkpoints and fire-and-forget operations
-- Only safe when the operation is idempotent or non-critical
-
-### Checkpoint Batching
-
-The SDK uses a background thread to batch multiple checkpoint operations into a single API call for efficiency. This reduces API overhead and
-improves throughput.
-
-```mermaid
-sequenceDiagram
-    participant MT as Main Thread
-    participant Q as Checkpoint Queue
-    participant BT as Background Thread
-    participant API as Durable Functions API
-    
-    Note over MT,API: Synchronous Checkpoint Flow
-    MT->>Q: Enqueue operation + completion event
-    MT->>MT: Block on completion event
-    BT->>Q: Collect batch (up to 1 second or 750KB)
-    BT->>API: POST /checkpoint (batched operations)
-    API-->>BT: New checkpoint token + operations
-    BT->>BT: Update execution state
-    BT->>MT: Signal completion event
-    MT->>MT: Resume execution
-    
-    Note over MT,API: Asynchronous Checkpoint Flow
-    MT->>Q: Enqueue operation (no event)
-    MT->>MT: Continue immediately
-    BT->>Q: Collect batch (up to 1 second or 750KB)
-    BT->>API: POST /checkpoint (batched operations)
-    API-->>BT: New checkpoint token + operations
-    BT->>BT: Update execution state
-```
-
-### Batching Configuration
-
-Checkpoint batching is controlled by `CheckpointBatcherConfig`:
-
-```python
-@dataclass(frozen=True)
-class CheckpointBatcherConfig:
-    max_batch_size_bytes: int = 750 * 1024  # 750KB
-    max_batch_time_seconds: float = 1.0     # 1 second
-    max_batch_operations: int | float = float("inf")  # No limit
-```
-
-The background thread collects operations until one of these limits is reached:
-1. Batch size exceeds 750KB
-2. 1 second has elapsed since the first operation
-3. Maximum operation count is reached (unlimited by default)
-
-### Concurrency Management
-
-The checkpointing system handles concurrent operations (map/parallel) by tracking parent-child relationships:
-
-1. When a CONTEXT operation completes (SUCCEED/FAIL), all descendant operations are marked as orphaned
-2. Orphaned operations are rejected if they attempt to checkpoint
-3. This prevents child operations from checkpointing after their parent has already completed
-4. Uses a single lock (`_parent_done_lock`) to coordinate completion and checkpoint validation
-
-### Error Handling
-
-When a checkpoint fails in the background thread:
-
-1. **Error Signaling**: The background thread creates a `BackgroundThreadError` wrapping the original exception
-2. **Event Notification**: All completion events (both in the current batch and queued operations) are signaled with this error
-3. **Immediate Propagation**: Synchronous callers waiting on `create_checkpoint(is_sync=True)` immediately receive the `BackgroundThreadError` 
-4. **Future Prevention**: A failure event (`_checkpointing_failed`) is set to prevent any future checkpoint attempts
-5. **Clean Termination**: The background thread exits cleanly after signaling all waiting operations
-
-For **synchronous operations** (default `is_sync=True`):
-- The main thread receives `BackgroundThreadError` immediately when calling `create_checkpoint()`
-- This prevents further execution with corrupted state
-
-For **asynchronous operations** (`is_sync=False`):
-- The error is detected on the next synchronous checkpoint attempt
-- The `_checkpointing_failed` event causes immediate failure before queuing
-
-This ensures no code continues executing after a checkpoint failure, maintaining execution state integrity.
-
-## License
-
-This project is licensed under the [Apache-2.0 License](LICENSE).