async-durable-execution 2.0.0a1__tar.gz → 2.0.0a2__tar.gz

{async_durable_execution-2.0.0a1 → async_durable_execution-2.0.0a2}/.gitignore

@@ -21,7 +21,7 @@ __pycache__/
 /build
 
 .venv
-.venv/
+.venv*/
 
 .attach_*
 

{async_durable_execution-2.0.0a1 → async_durable_execution-2.0.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: async-durable-execution
-Version: 2.0.0a1
+Version: 2.0.0a2
 Summary: Community-maintained durable execution SDK for AWS Lambda in Python
 Project-URL: Documentation, https://github.com/zhongkechen/async-durable-execution#readme
 Project-URL: Issues, https://github.com/zhongkechen/async-durable-execution/issues
@@ -9,14 +9,17 @@ Author: Zhongke Chen
 License-Expression: Apache-2.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
 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-Python: >=3.10
 Requires-Dist: boto3>=1.42.1
+Provides-Extra: typing
+Requires-Dist: boto3-stubs[lambda]>=1.42.1; extra == 'typing'
 Description-Content-Type: text/markdown
 
 # Async Durable Execution for Python
@@ -33,17 +36,17 @@ Build reliable, long-running AWS Lambda workflows with checkpointed steps, waits
 
 This package is distributed from a community-maintained fork of the original Apache-2.0 licensed AWS project and continues under Apache License 2.0 with upstream notices preserved.
 
-This fork is specifically focused on making async Python work naturally with durable functions. The public API remains synchronous at the durable operation boundary, but the examples, helpers, and package direction here prioritize `async def` handlers, steps, child contexts, callback submitters, and condition checks.
+This fork is specifically focused on making async Python work naturally with durable functions. The public API remains synchronous at the durable operation boundary, but user-provided durable callables must now use `async def` for handlers, steps, child contexts, callback submitters, and condition checks.
 
 ## ✨ Key Features
 
-- **Async-first fork** - This fork prioritizes making `async def` workflows feel natural with durable functions
+- **Async-only user callables** - Durable handlers and user-provided durable callbacks must use `async def`
 - **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
+- **Replay-safe logging** - Use standard `logging` loggers enriched by the durable context filter
 - **Local and cloud testing** - Validate workflows with the testing SDK
 - **Async Python support** - Use `async def` for handlers, steps, child contexts, callback submitters, and wait-for-condition checks
 
@@ -57,7 +60,8 @@ This fork is specifically focused on making async Python work naturally with dur
 
 ## 🚀 Quick Start
 
-This fork recommends writing new durable workflows with async callables by default.
+This fork now requires async callables for all user-provided durable code.
+Requires Python 3.10 or newer.
 
 Install the execution SDK:
 
@@ -69,61 +73,66 @@ Create a durable Lambda handler:
 
 ```python
 import asyncio
+import logging
+from datetime import timedelta
 
 from async_durable_execution import (
-    DurableContext,
-    StepContext,
-    durable_execution,
     durable_step,
+    durable_execution,
+    step,
+    wait,
 )
-from async_durable_execution.config import Duration
+
+logger = logging.getLogger(__name__)
 
 
 @durable_step
-async def validate_order(step_ctx: StepContext, order_id: str) -> dict:
+async def validate_order(order_id: str) -> dict:
     await asyncio.sleep(0)
-    step_ctx.logger.info("Validating order", extra={"order_id": order_id})
+    logger.info("Validating order", extra={"order_id": order_id})
     return {"order_id": order_id, "valid": True}
 
 
 @durable_execution
-async def handler(event: dict, context: DurableContext) -> dict:
+async def handler(event: dict) -> dict:
     order_id = event["order_id"]
-    context.logger.info("Starting workflow", extra={"order_id": order_id})
+    logger.info("Starting workflow", extra={"order_id": order_id})
 
-    validation = context.step(validate_order(order_id), name="validate_order")
+    validation = await 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")
+    await wait(duration=timedelta(seconds=5), name="await_confirmation")
 
     return {"status": "approved", "order_id": order_id}
 ```
 
-Async callables are supported anywhere the SDK accepts user code, including `map()` item functions, `parallel()` branches, child contexts, callback submitters, and wait-for-condition checks. The public Durable APIs stay synchronous, so async work is awaited transparently for you:
+Async callables are required anywhere the SDK accepts user code, including `map()` item functions, `parallel()` branches, child contexts, callback submitters, and wait-for-condition checks. Durable context operations are awaitable and run on the same event loop as your handler:
 
 ```python
 import asyncio
+import logging
 
 from async_durable_execution import (
-    DurableContext,
-    StepContext,
-    durable_execution,
     durable_step,
+    durable_execution,
+    step,
 )
 
+logger = logging.getLogger(__name__)
+
 
 @durable_step
-async def fetch_order(step_ctx: StepContext, order_id: str) -> dict:
+async def fetch_order(order_id: str) -> dict:
     await asyncio.sleep(0)
-    step_ctx.logger.info("Fetched order", extra={"order_id": order_id})
+    logger.info("Fetched order", extra={"order_id": order_id})
     return {"order_id": order_id, "status": "ready"}
 
 
 @durable_execution
-async def handler(event: dict, context: DurableContext) -> dict:
-    order = context.step(fetch_order(event["order_id"]), name="fetch_order")
+async def handler(event: dict) -> dict:
+    order = await step(fetch_order(event["order_id"]), name="fetch_order")
     return {"order": order}
 ```
 

{async_durable_execution-2.0.0a1 → async_durable_execution-2.0.0a2}/README.md

@@ -12,17 +12,17 @@ Build reliable, long-running AWS Lambda workflows with checkpointed steps, waits
 
 This package is distributed from a community-maintained fork of the original Apache-2.0 licensed AWS project and continues under Apache License 2.0 with upstream notices preserved.
 
-This fork is specifically focused on making async Python work naturally with durable functions. The public API remains synchronous at the durable operation boundary, but the examples, helpers, and package direction here prioritize `async def` handlers, steps, child contexts, callback submitters, and condition checks.
+This fork is specifically focused on making async Python work naturally with durable functions. The public API remains synchronous at the durable operation boundary, but user-provided durable callables must now use `async def` for handlers, steps, child contexts, callback submitters, and condition checks.
 
 ## ✨ Key Features
 
-- **Async-first fork** - This fork prioritizes making `async def` workflows feel natural with durable functions
+- **Async-only user callables** - Durable handlers and user-provided durable callbacks must use `async def`
 - **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
+- **Replay-safe logging** - Use standard `logging` loggers enriched by the durable context filter
 - **Local and cloud testing** - Validate workflows with the testing SDK
 - **Async Python support** - Use `async def` for handlers, steps, child contexts, callback submitters, and wait-for-condition checks
 
@@ -36,7 +36,8 @@ This fork is specifically focused on making async Python work naturally with dur
 
 ## 🚀 Quick Start
 
-This fork recommends writing new durable workflows with async callables by default.
+This fork now requires async callables for all user-provided durable code.
+Requires Python 3.10 or newer.
 
 Install the execution SDK:
 
@@ -48,61 +49,66 @@ Create a durable Lambda handler:
 
 ```python
 import asyncio
+import logging
+from datetime import timedelta
 
 from async_durable_execution import (
-    DurableContext,
-    StepContext,
-    durable_execution,
     durable_step,
+    durable_execution,
+    step,
+    wait,
 )
-from async_durable_execution.config import Duration
+
+logger = logging.getLogger(__name__)
 
 
 @durable_step
-async def validate_order(step_ctx: StepContext, order_id: str) -> dict:
+async def validate_order(order_id: str) -> dict:
     await asyncio.sleep(0)
-    step_ctx.logger.info("Validating order", extra={"order_id": order_id})
+    logger.info("Validating order", extra={"order_id": order_id})
     return {"order_id": order_id, "valid": True}
 
 
 @durable_execution
-async def handler(event: dict, context: DurableContext) -> dict:
+async def handler(event: dict) -> dict:
     order_id = event["order_id"]
-    context.logger.info("Starting workflow", extra={"order_id": order_id})
+    logger.info("Starting workflow", extra={"order_id": order_id})
 
-    validation = context.step(validate_order(order_id), name="validate_order")
+    validation = await 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")
+    await wait(duration=timedelta(seconds=5), name="await_confirmation")
 
     return {"status": "approved", "order_id": order_id}
 ```
 
-Async callables are supported anywhere the SDK accepts user code, including `map()` item functions, `parallel()` branches, child contexts, callback submitters, and wait-for-condition checks. The public Durable APIs stay synchronous, so async work is awaited transparently for you:
+Async callables are required anywhere the SDK accepts user code, including `map()` item functions, `parallel()` branches, child contexts, callback submitters, and wait-for-condition checks. Durable context operations are awaitable and run on the same event loop as your handler:
 
 ```python
 import asyncio
+import logging
 
 from async_durable_execution import (
-    DurableContext,
-    StepContext,
-    durable_execution,
     durable_step,
+    durable_execution,
+    step,
 )
 
+logger = logging.getLogger(__name__)
+
 
 @durable_step
-async def fetch_order(step_ctx: StepContext, order_id: str) -> dict:
+async def fetch_order(order_id: str) -> dict:
     await asyncio.sleep(0)
-    step_ctx.logger.info("Fetched order", extra={"order_id": order_id})
+    logger.info("Fetched order", extra={"order_id": order_id})
     return {"order_id": order_id, "status": "ready"}
 
 
 @durable_execution
-async def handler(event: dict, context: DurableContext) -> dict:
-    order = context.step(fetch_order(event["order_id"]), name="fetch_order")
+async def handler(event: dict) -> dict:
+    order = await step(fetch_order(event["order_id"]), name="fetch_order")
     return {"order": order}
 ```
 

{async_durable_execution-2.0.0a1 → async_durable_execution-2.0.0a2}/VERSION.py

@@ -2,4 +2,4 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 # Modified for the async-durable-execution fork; shared version source for all packages.
-__version__ = "2.0.0a1"
+__version__ = "2.0.0a2"

{async_durable_execution-2.0.0a1 → async_durable_execution-2.0.0a2}/pyproject.toml

@@ -8,13 +8,14 @@ name = "async-durable-execution"
 dynamic = ["version"]
 description = "Community-maintained durable execution SDK for AWS Lambda in Python"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.10"
 license = "Apache-2.0"
 keywords = []
 authors = [{ name = "Zhongke Chen" }]
 classifiers = [
   "Development Status :: 4 - Beta",
   "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
@@ -24,6 +25,9 @@ classifiers = [
 ]
 dependencies = ["boto3>=1.42.1"]
 
+[project.optional-dependencies]
+typing = ["boto3-stubs[lambda]>=1.42.1"]
+
 [project.urls]
 Documentation = "https://github.com/zhongkechen/async-durable-execution#readme"
 Issues = "https://github.com/zhongkechen/async-durable-execution/issues"
@@ -62,11 +66,11 @@ exclude_lines = ["no cov", "if __name__ == .__main__.:", "if TYPE_CHECKING:"]
 
 [tool.ruff]
 line-length = 88
-target-version = "py311"
+target-version = "py310"
 
 [tool.ruff.lint]
 preview = true
-select = ["TID252"]  # Enforce absolute imports (ban relative imports)
+select = []
 
 [tool.ruff.lint.isort]
 known-first-party = ["async_durable_execution"]
@@ -74,7 +78,7 @@ force-single-line = false
 lines-after-imports = 2
 
 [tool.ruff.lint.per-file-ignores]
-"tests/**" = [
+"tests_async_durable_execution/**" = [
   "ARG001",
   "ARG002",
   "ARG005",

async_durable_execution-2.0.0a2/src/async_durable_execution/__init__.py

@@ -0,0 +1,132 @@
+"""AWS Lambda Durable Executions Python SDK."""
+
+# Package metadata
+from .__about__ import __version__
+
+# Main context - used in every durable function
+# Helper decorators - commonly used for step functions
+# Concurrency
+from .models import (
+    BatchItem,
+    BatchItemStatus,
+    BatchResult,
+    CompletionReason,
+    InvocationStatus,
+    OperationType,
+    OperationStatus,
+)
+from .config import (
+    CallbackConfig,
+    CompletionConfig,
+    MapConfig,
+    NestingType,
+    ParallelBranch,
+    ParallelConfig,
+    RetryPresets,
+    RetryStrategyBuilder,
+    StepConfig,
+    StepSemantics,
+    WaitStrategyBuilder,
+    WaitForCallbackConfig,
+    WaitForConditionConfig,
+    WithRetryConfig,
+)
+from .context import (
+    get_current_context,
+)
+from .operation.with_retry import with_retry
+from .operation.map import map
+from .operation.wait_for_condition import (
+    wait_for_condition,
+    WaitForConditionCheckContext,
+)
+from .operation.invoke import invoke
+from .operation.parallel import parallel, durable_parallel_branch
+from .operation.callback import (
+    create_callback,
+    durable_wait_for_callback,
+    wait_for_callback,
+    WaitForCallbackContext,
+    Callback,
+)
+from .operation.child import durable_child_context, run_in_child_context, DurableContext
+from .operation.step import step, durable_step, StepContext, get_attempt
+from .models import (
+    ErrorObject,
+    OperationIdentifier,
+    RetryDecision,
+    WaitDecision,
+    WaitForConditionDecision,
+)
+
+# Most common exceptions - users need to handle these exceptions
+from .exceptions import (
+    DurableExecutionsError,
+    InvocationError,
+    ValidationError,
+)
+
+# Core decorator - used in every durable function
+from .execution import durable_execution
+from .operation.wait import wait
+from .plugin import DurableInstrumentationPlugin
+from .serdes import JsonSerDes, SerDes, SerDesContext
+
+__all__ = [
+    "BatchItem",
+    "BatchItemStatus",
+    "BatchResult",
+    "Callback",
+    "CallbackConfig",
+    "CompletionConfig",
+    "CompletionReason",
+    "DurableContext",
+    "DurableInstrumentationPlugin",
+    "DurableExecutionsError",
+    "ErrorObject",
+    "InvocationError",
+    "JsonSerDes",
+    "MapConfig",
+    "NestingType",
+    "OperationIdentifier",
+    "ParallelBranch",
+    "ParallelConfig",
+    "RetryDecision",
+    "RetryPresets",
+    "RetryStrategyBuilder",
+    "SerDes",
+    "SerDesContext",
+    "StepConfig",
+    "StepContext",
+    "StepSemantics",
+    "ValidationError",
+    "WaitForCallbackConfig",
+    "WaitForCallbackContext",
+    "WaitDecision",
+    "WaitForConditionCheckContext",
+    "WaitForConditionConfig",
+    "WaitForConditionDecision",
+    "WaitStrategyBuilder",
+    "WithRetryConfig",
+    "__version__",
+    "create_callback",
+    "durable_execution",
+    "durable_parallel_branch",
+    "durable_step",
+    "durable_wait_for_callback",
+    "get_attempt",
+    "get_current_context",
+    "invoke",
+    "map",
+    "parallel",
+    "run_in_child_context",
+    "step",
+    "wait",
+    "wait_for_callback",
+    "wait_for_condition",
+    "with_retry",
+    "InvocationStatus",
+    "OperationType",
+    "OperationStatus",
+    "durable_child_context",
+]

async_durable_execution-2.0.0a2/src/async_durable_execution/async_tools.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, TypeVar, cast
+
+from .context import reset_current_context, set_current_context
+from .exceptions import ValidationError
+
+if TYPE_CHECKING:
+    from . import DurableContext
+
+T = TypeVar("T")
+_CONTEXT_PARAM_NAMES = {
+    "context",
+    "ctx",
+    "child_context",
+    "child_ctx",
+    "durable_context",
+    "durable_ctx",
+}
+
+
+def is_async_callable(func: Callable[..., object]) -> bool:
+    if inspect.iscoroutinefunction(func):
+        return True
+    if isinstance(func, functools.partial):
+        return is_async_callable(func.func)
+
+    call = getattr(func, "__call__", None)
+    return call is not None and inspect.iscoroutinefunction(call)
+
+
+def get_callable_name(
+    func: Callable[..., object],
+    *,
+    include_original_name: bool = True,
+) -> str | None:
+    if isinstance(func, functools.partial):
+        return get_callable_name(
+            func.func,
+            include_original_name=include_original_name,
+        )
+
+    if include_original_name:
+        original_name = getattr(func, "_original_name", None)
+        if original_name is not None:
+            return original_name
+
+    if inspect.isfunction(func) or inspect.ismethod(func):
+        return getattr(func, "__name__", None)
+
+    return None
+
+
+def assert_async_callable(
+    func: Callable[..., object],
+    *,
+    label: str = "func",
+) -> None:
+    if is_async_callable(func):
+        return
+
+    name = get_callable_name(func)
+    if name is None:
+        name = type(func).__name__
+
+    msg = (
+        f"`{label}` must be an async function. "
+        f"Non-async callables are no longer supported: {name}."
+    )
+    raise ValidationError(msg)
+
+
+async def invoke_callable(func: Callable[..., Awaitable[T]], *args, **kwargs) -> T:
+    assert_async_callable(func)
+    return await func(*args, **kwargs)
+
+
+async def invoke_user_callable(
+    context: DurableContext,
+    func: Callable[..., Awaitable[T]],
+    *args,
+    **kwargs,
+) -> T:
+    token = set_current_context(context)
+    try:
+        return await invoke_callable(
+            func,
+            *args,
+            **kwargs,
+        )
+    finally:
+        reset_current_context(token)

async_durable_execution-2.0.0a2/src/async_durable_execution/client.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, cast
+
+import boto3
+from botocore.config import Config
+
+from .__about__ import __version__
+from .exceptions import CheckpointError, GetExecutionStateError
+from .models import (
+    CheckpointOutput,
+    OperationUpdate,
+    StateOutput,
+)
+from .types import DurableServiceClient, LambdaApiClient
+
+logger = logging.getLogger(__name__)
+
+
+def create_default_client():
+    user_agent = f"async-durable-execution/{__version__}-async"
+    return boto3.client(
+        "lambda",
+        config=Config(
+            connect_timeout=5,
+            read_timeout=50,
+            user_agent_extra=user_agent,
+        ),
+    )
+
+
+class ThreadedSyncLambdaClient(DurableServiceClient):
+    """Adapt the sync boto3 Lambda client to the async service interface."""
+
+    _cached_boto_client: LambdaApiClient | None = None
+
+    def __init__(self, client: LambdaApiClient | None) -> None:
+        self.client = client or create_default_client()
+
+    async def checkpoint(
+        self,
+        durable_execution_arn: str,
+        checkpoint_token: str,
+        updates: list[OperationUpdate],
+        client_token: str | None,
+    ) -> CheckpointOutput:
+        try:
+            optional_params: dict[str, str] = {}
+            if client_token is not None:
+                optional_params["ClientToken"] = client_token
+
+            result = await asyncio.to_thread(
+                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)
+        except Exception as e:
+            checkpoint_error = CheckpointError.from_exception(e)
+            logger.exception(
+                "Failed to checkpoint.", extra=checkpoint_error.build_logger_extras()
+            )
+            raise checkpoint_error from None
+
+    async def get_execution_state(
+        self,
+        durable_execution_arn: str,
+        checkpoint_token: str,
+        next_marker: str,
+        max_items: int = 1000,
+    ) -> StateOutput:
+        try:
+            result = await asyncio.to_thread(
+                self.client.get_durable_execution_state,
+                DurableExecutionArn=durable_execution_arn,
+                CheckpointToken=checkpoint_token,
+                Marker=next_marker,
+                MaxItems=max_items,
+            )
+            return StateOutput.from_dict(result)
+        except Exception as e:
+            error = GetExecutionStateError.from_exception(e)
+            logger.exception(
+                "Failed to get execution state.", extra=error.build_logger_extras()
+            )
+            raise error from None
+
+
+__all__ = ["ThreadedSyncLambdaClient"]