aws-durable-execution-sdk-python 1.3.0__py3-none-any.whl → 1.5.0__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.3.0"
+__version__ = "1.5.0"

aws_durable_execution_sdk_python/__init__.py

@@ -1,11 +1,16 @@
 """AWS Lambda Durable Executions Python SDK."""
 
+# Package metadata
+from aws_durable_execution_sdk_python.__about__ import __version__
+
 # Main context - used in every durable function
 # Helper decorators - commonly used for step functions
 # Concurrency
 from aws_durable_execution_sdk_python.concurrency.models import BatchResult
+from aws_durable_execution_sdk_python.config import ParallelBranch
 from aws_durable_execution_sdk_python.context import (
     DurableContext,
+    durable_parallel_branch,
     durable_step,
     durable_wait_for_callback,
     durable_with_child_context,
@@ -24,14 +29,18 @@ from aws_durable_execution_sdk_python.execution import durable_execution
 # Essential context types - passed to user functions
 from aws_durable_execution_sdk_python.types import StepContext
 
+
 __all__ = [
     "BatchResult",
     "DurableContext",
     "DurableExecutionsError",
     "InvocationError",
+    "ParallelBranch",
     "StepContext",
     "ValidationError",
+    "__version__",
     "durable_execution",
+    "durable_parallel_branch",
     "durable_step",
     "durable_wait_for_callback",
     "durable_with_child_context",

aws_durable_execution_sdk_python/concurrency/executor.py

@@ -20,7 +20,10 @@ from aws_durable_execution_sdk_python.concurrency.models import (
     ExecutionCounters,
     SuspendResult,
 )
-from aws_durable_execution_sdk_python.config import ChildConfig
+from aws_durable_execution_sdk_python.config import (
+    ChildConfig,
+    NestingType,
+)
 from aws_durable_execution_sdk_python.exceptions import (
     OrphanedChildException,
     SuspendExecution,
@@ -30,6 +33,7 @@ from aws_durable_execution_sdk_python.identifier import OperationIdentifier
 from aws_durable_execution_sdk_python.lambda_service import ErrorObject
 from aws_durable_execution_sdk_python.operation.child import child_handler
 
+
 if TYPE_CHECKING:
     from collections.abc import Callable
 
@@ -142,6 +146,7 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
         serdes: SerDes | None,
         item_serdes: SerDes | None = None,
         summary_generator: SummaryGenerator | None = None,
+        nesting_type: NestingType = NestingType.NESTED,
     ):
         """Initialize ConcurrentExecutor.
 
@@ -159,6 +164,7 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
         self.sub_type_iteration = sub_type_iteration
         self.name_prefix = name_prefix
         self.summary_generator = summary_generator
+        self.nesting_type = nesting_type
 
         # Event-driven state tracking for when the executor is done
         self._completion_event = threading.Event()
@@ -188,6 +194,14 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
         """Execute a single executable in a child context and return the result."""
         raise NotImplementedError
 
+    def get_iteration_name(self, index: int) -> str:
+        """Get the display name for an iteration/branch at the given index.
+
+        Subclasses can override this to provide custom naming (e.g., from item_namer
+        or branch names). The default returns "{name_prefix}{index}".
+        """
+        return f"{self.name_prefix}{index}"
+
     def execute(
         self, execution_state: ExecutionState, executor_context: DurableContext
     ) -> BatchResult[ResultType]:
@@ -196,6 +210,11 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
             "▶️ Executing concurrent operation, items: %d", len(self.executables)
         )
 
+        # Early return for empty executables
+        if not self.executables:
+            logger.debug("No items to execute, returning empty result")
+            return self._create_result()
+
         max_workers = self.max_concurrency or len(self.executables)
 
         self.executables_with_state = [
@@ -385,29 +404,36 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
         """
         Execute a single item in a derived child context.
 
-        instead of relying on `executor_context.run_in_child_context`
-        we generate an operation_id for the child, and then call `child_handler`
-        directly. This avoids the hidden mutation of the context's internal counter.
-        we can do this because we explicitly control the generation of step_id and do it
-        using executable.index.
-
+        Instead of relying on `executor_context.run_in_child_context` we
+        generate an operation_id for the child, then call `child_handler`
+        directly. This avoids the hidden mutation of the context's
+        internal counter. We explicitly derive the child's operation_id
+        from `executable.index` so that the same input always produces
+        the same id regardless of the order branches actually run in.
 
-        invariant: `operation_id` for a given executable is deterministic,
-            and execution order invariant.
+        Invariant: `operation_id` for a given executable is deterministic
+        and execution-order invariant.
         """
 
-        operation_id = executor_context._create_step_id_for_logical_step(  # noqa: SLF001
+        operation_id: str = executor_context._create_step_id_for_logical_step(  # noqa: SLF001
             executable.index
         )
-        name = f"{self.name_prefix}{executable.index}"
-        child_context = executor_context.create_child_context(operation_id)
+        name: str = self.get_iteration_name(executable.index)
+        is_virtual: bool = self.nesting_type is NestingType.FLAT
+
+        child_context: DurableContext = executor_context.create_child_context(
+            operation_id, is_virtual=is_virtual
+        )
+        # For NESTED this is for branch's START/SUCCEED/FAIL checkpoints (not the children of the branch).
+        # For FLAT `child_handler` skips checkpoints, so not used.
+        # Construct it unconditionally to keep the call simple.
         operation_identifier = OperationIdentifier(
             operation_id,
             executor_context._parent_id,  # noqa: SLF001
             name,
         )
 
-        def run_in_child_handler():
+        def run_in_child_handler() -> ResultType:
             return self.execute_item(child_context, executable)
 
         result: ResultType = child_handler(
@@ -418,6 +444,7 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
                 serdes=self.item_serdes or self.serdes,
                 sub_type=self.sub_type_iteration,
                 summary_generator=self.summary_generator,
+                is_virtual=is_virtual,
             ),
         )
         child_context.state.track_replay(operation_id=operation_id)

aws_durable_execution_sdk_python/concurrency/models.py

@@ -114,6 +114,85 @@ class BatchResult(Generic[R], BatchResultProtocol[R]):  # noqa: PYI059
         completion_reason = CompletionReason(completion_reason_value)
         return cls(batch_items, completion_reason)
 
+    @staticmethod
+    def _get_completion_reason(
+        failure_count: int,
+        success_count: int,
+        completed_count: int,
+        total_count: int,
+        completion_config: CompletionConfig | None,
+    ) -> CompletionReason:
+        """
+        Determine completion reason based on completion counts.
+
+        Logic order:
+        1. Check failure tolerance FIRST (before checking if all completed)
+        2. Check if all completed
+        3. Check if minimum successful reached
+        4. Default to ALL_COMPLETED
+
+        Args:
+            failure_count: Number of failed items
+            success_count: Number of succeeded items
+            completed_count: Total completed (succeeded + failed)
+            total_count: Total number of items
+            completion_config: Optional completion configuration
+
+        Returns:
+            CompletionReason enum value
+        """
+        # STEP 1: Check tolerance first, before checking if all completed
+
+        # Handle fail-fast behavior (no completion config or empty completion config)
+        if completion_config is None:
+            if failure_count > 0:
+                return CompletionReason.FAILURE_TOLERANCE_EXCEEDED
+        else:
+            # Check if completion config has any criteria set
+            has_any_completion_criteria = (
+                completion_config.min_successful is not None
+                or completion_config.tolerated_failure_count is not None
+                or completion_config.tolerated_failure_percentage is not None
+            )
+
+            if not has_any_completion_criteria:
+                # Empty completion config - fail fast on any failure
+                if failure_count > 0:
+                    return CompletionReason.FAILURE_TOLERANCE_EXCEEDED
+            else:
+                # Check specific tolerance thresholds
+                if (
+                    completion_config.tolerated_failure_count is not None
+                    and failure_count > completion_config.tolerated_failure_count
+                ):
+                    return CompletionReason.FAILURE_TOLERANCE_EXCEEDED
+
+                if (
+                    completion_config.tolerated_failure_percentage is not None
+                    and total_count > 0
+                ):
+                    failure_percentage = (failure_count / total_count) * 100
+                    if (
+                        failure_percentage
+                        > completion_config.tolerated_failure_percentage
+                    ):
+                        return CompletionReason.FAILURE_TOLERANCE_EXCEEDED
+
+        # STEP 2: Check if all completed
+        if completed_count == total_count:
+            return CompletionReason.ALL_COMPLETED
+
+        # STEP 3: Check if minimum successful reached
+        if (
+            completion_config is not None
+            and completion_config.min_successful is not None
+            and success_count >= completion_config.min_successful
+        ):
+            return CompletionReason.MIN_SUCCESSFUL_REACHED
+
+        # STEP 4: Default
+        return CompletionReason.ALL_COMPLETED
+
     @classmethod
     def from_items(
         cls,
@@ -123,12 +202,8 @@ class BatchResult(Generic[R], BatchResultProtocol[R]):  # noqa: PYI059
         """
         Infer completion reason based on batch item statuses and completion config.
 
-        This follows the same logic as the TypeScript implementation:
-        - If all items completed: ALL_COMPLETED
-        - If minSuccessful threshold met and not all completed: MIN_SUCCESSFUL_REACHED
-        - Otherwise: FAILURE_TOLERANCE_EXCEEDED
+        This follows the same logic as the TypeScript implementation.
         """
-
         statuses = (item.status for item in items)
         counts = Counter(statuses)
         succeeded_count = counts.get(BatchItemStatus.SUCCEEDED, 0)
@@ -138,18 +213,14 @@ class BatchResult(Generic[R], BatchResultProtocol[R]):  # noqa: PYI059
         completed_count = succeeded_count + failed_count
         total_count = started_count + completed_count
 
-        # If all items completed (no started items), it's ALL_COMPLETED
-        if completed_count == total_count:
-            completion_reason = CompletionReason.ALL_COMPLETED
-        elif (  # If we have completion config and minSuccessful threshold is met
-            completion_config
-            and (min_successful := completion_config.min_successful) is not None
-            and succeeded_count >= min_successful
-        ):
-            completion_reason = CompletionReason.MIN_SUCCESSFUL_REACHED
-        else:
-            # Otherwise, assume failure tolerance was exceeded
-            completion_reason = CompletionReason.FAILURE_TOLERANCE_EXCEEDED
+        # Determine completion reason using the same logic as JavaScript SDK
+        completion_reason = cls._get_completion_reason(
+            failure_count=failed_count,
+            success_count=succeeded_count,
+            completed_count=completed_count,
+            total_count=total_count,
+            completion_config=completion_config,
+        )
 
         return cls(items, completion_reason)
 

aws_durable_execution_sdk_python/config.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Generic, TypeVar
 
 from aws_durable_execution_sdk_python.exceptions import ValidationError
 
+
 P = TypeVar("P")  # Payload type
 R = TypeVar("R")  # Result type
 T = TypeVar("T")
@@ -76,6 +77,42 @@ class TerminationMode(Enum):
     ABANDON = "ABANDON"
 
 
+class NestingType(Enum):
+    """Control how child contexts are created for batch operations.
+
+    Applies to `map` and `parallel`. Each branch or iteration runs inside a
+    child context.
+
+        - NESTED: full checkpointed context
+        - FLAT: a virtual context that skips checkpoints for the branch/iteration.
+
+    """
+
+    NESTED = "NESTED"
+    """Create CONTEXT operations for each branch/iteration with full checkpointing.
+
+    Operations within each branch/iteration are wrapped in their own context.
+
+    - Observability: high — each branch/iteration appears as a separate
+      operation in execution history.
+    - Cost: higher — consumes more operations due to CONTEXT creation
+      overhead.
+    - Scale: lower maximum iterations due to operation limits.
+    """
+
+    FLAT = "FLAT"
+    """Skip CONTEXT operations for branches/iterations using virtual contexts.
+
+    Operations execute directly without individual context wrapping.
+
+    - Observability: lower — branches/iterations don't appear as separate
+      operations in execution history.
+    - Cost: ~30% lower — reduces operation consumption by skipping CONTEXT
+      overhead.
+    - Scale: higher maximum iterations possible within operation limits.
+    """
+
+
 @dataclass(frozen=True)
 class CompletionConfig:
     """Configuration for determining when parallel/map operations complete.
@@ -187,6 +224,10 @@ class ParallelConfig:
             Used internally by map/parallel operations to handle large BatchResult payloads.
             Signature: (result: T) -> str
 
+        nesting_type: How child operations should inherit context from their parent.
+            - NESTED: Each branch runs in its own isolated context (default)
+            - FLAT: All branches share the same parent context
+
     Example:
         # Run at most 3 branches concurrently, succeed if any one succeeds
         config = ParallelConfig(
@@ -202,6 +243,42 @@ class ParallelConfig:
     serdes: SerDes | None = None
     item_serdes: SerDes | None = None
     summary_generator: SummaryGenerator | None = None
+    nesting_type: NestingType = NestingType.NESTED
+
+
+@dataclass(frozen=True)
+class ParallelBranch(Generic[T]):
+    """A named branch for parallel execution.
+
+    Use this to provide custom names for parallel branches, improving
+    observability in execution history.
+
+    Type Parameters:
+        T: The return type of the branch function.
+
+    Args:
+        func: The callable to execute in this branch. Receives a DurableContext.
+        name: Optional custom name for this branch. When provided, replaces
+            the default "parallel-branch-{index}" naming in execution history.
+            This affects observability but not replay determinism.
+
+    Example:
+        context.parallel(
+            functions=[
+                ParallelBranch(func=lambda ctx: fetch_user(ctx), name="fetch-user-data"),
+                ParallelBranch(func=lambda ctx: fetch_orders(ctx), name="fetch-order-history"),
+            ],
+            name="load-data",
+            config=ParallelConfig(max_concurrency=2),
+        )
+    """
+
+    func: Callable
+    name: str | None = None
+
+    def __call__(self, *args, **kwargs):
+        """Delegate to the wrapped function, making ParallelBranch itself callable."""
+        return self.func(*args, **kwargs)
 
 
 class StepSemantics(Enum):
@@ -218,12 +295,6 @@ class StepConfig:
     serdes: SerDes | None = None
 
 
-class CheckpointMode(Enum):
-    NO_CHECKPOINT = ("NO_CHECKPOINT",)
-    CHECKPOINT_AT_FINISH = ("CHECKPOINT_AT_FINISH",)
-    CHECKPOINT_AT_START_AND_FINISH = "CHECKPOINT_AT_START_AND_FINISH"
-
-
 @dataclass(frozen=True)
 class ChildConfig(Generic[T]):
     """Configuration options for child context operations.
@@ -259,21 +330,23 @@ class ChildConfig(Generic[T]):
 
             Used internally by map/parallel operations to handle large BatchResult payloads.
             Signature: (result: T) -> str
-    Note:
-        checkpoint_mode field is commented out as it's not currently implemented.
-        When implemented, it will control when checkpoints are created:
-        - CHECKPOINT_AT_START_AND_FINISH: Checkpoint at both start and completion (default)
-        - CHECKPOINT_AT_FINISH: Only checkpoint when operation completes
-        - NO_CHECKPOINT: No automatic checkpointing
+
+        is_virtual: When True, skip all checkpoints (START, SUCCEED,
+            FAIL) for this child context and propagate the caller's reporting
+            parent id through to operations created inside the child. The
+            branch is a logical scope for step-id prefixing but does not
+            appear in the execution history. Used internally by
+            NestingType.FLAT branches. Use this to group operations without
+            adding a CONTEXT entry to the execution history.
 
     See TypeScript reference: aws-durable-execution-sdk-js/src/types/index.ts
     """
 
-    # checkpoint_mode: CheckpointMode = CheckpointMode.CHECKPOINT_AT_START_AND_FINISH
     serdes: SerDes | None = None
     item_serdes: SerDes | None = None
     sub_type: OperationSubType | None = None
     summary_generator: SummaryGenerator | None = None
+    is_virtual: bool = False
 
 
 class ItemsPerBatchUnit(Enum):
@@ -317,12 +390,15 @@ class ItemBatcher(Generic[T]):
 
 
 @dataclass(frozen=True)
-class MapConfig:
+class MapConfig(Generic[T]):
     """Configuration options for map operations over collections.
 
     This class configures how map operations process collections of items,
     including concurrency, batching, completion criteria, and serialization.
 
+    Type Parameters:
+        T: The type of items being processed in the map operation.
+
     Args:
         max_concurrency: Maximum number of items to process concurrently.
             If None, no limit is imposed and all items are processed concurrently.
@@ -361,6 +437,16 @@ class MapConfig:
             Used internally by map/parallel operations to handle large BatchResult payloads.
             Signature: (result: T) -> str
 
+        nesting_type: How child operations should inherit context from their parent.
+            - NESTED: Each item runs in its own isolated context (default)
+            - FLAT: All items share the same parent context
+
+        item_namer: Optional callable to generate custom names for each map iteration.
+            When provided, replaces the default "map-item-{index}" naming scheme.
+            Receives the item and its index, and returns a string name for that iteration.
+            This affects observability (execution history names) but not replay determinism.
+            If None, uses the default naming: "map-item-{index}".
+
     Example:
         # Process 5 items at a time, batch by count, require all to succeed
         config = MapConfig(
@@ -368,6 +454,12 @@ class MapConfig:
             item_batcher=ItemBatcher(max_items_per_batch=10),
             completion_config=CompletionConfig.all_successful()
         )
+
+        # With custom iteration names
+        config = MapConfig(
+            max_concurrency=5,
+            item_namer=lambda item, index: f"process-order-{item.id}"
+        )
     """
 
     max_concurrency: int | None = None
@@ -376,6 +468,8 @@ class MapConfig:
     serdes: SerDes | None = None
     item_serdes: SerDes | None = None
     summary_generator: SummaryGenerator | None = None
+    nesting_type: NestingType = NestingType.NESTED
+    item_namer: Callable[[T, int], str] | None = None
 
 
 @dataclass(frozen=True)