Parallel¶

Internal implementation module: async_durable_execution._operation.parallel.

Use parallel() for explicit durable branches and configurable batch completion behavior.

Concurrent executor for parallel and map operations.

Classes¶

CompletionReason ¶

Bases: Enum

Why a map() or parallel() operation stopped collecting results.

Values

ALL_COMPLETED: Every item or branch reached a terminal state and no earlier success, failure, or custom completion condition applied. MIN_SUCCESSFUL_REACHED: The configured min_successful threshold was reached. FAILURE_TOLERANCE_EXCEEDED: The number of failures exceeded the configured tolerated_failure_count, or no failure tolerance was configured and at least one failure was observed. CUSTOM_COMPLETION_SUCCEEDED: A custom completion function completed the operation successfully. CUSTOM_COMPLETION_FAILED: A custom completion function completed the operation as failed.

Attributes¶

is_succeeded `property` ¶

is_succeeded: bool

Whether this completion reason represents successful completion.

CompletionStatus `dataclass` ¶

CompletionStatus(
    success_count: int, failure_count: int, total_count: int
)

Live completion progress passed to a custom completion function.

Attributes:

Name	Type	Description
`success_count`	`int`	Number of items or branches that have completed successfully.
`failure_count`	`int`	Number of items or branches that have failed.
`total_count`	`int`	Total number of items or branches registered for the operation.
`completed_count`	`int`	Calculated number of terminal items or branches, equal to `success_count + failure_count`.
`all_completed`	`bool`	Whether every registered item or branch is terminal.

Raises:

Type	Description
`ValueError`	If any count is negative, or if completed count exceeds `total_count`.

Attributes¶

completed_count `property` ¶

completed_count: int

Number of items that have reached a terminal state.

all_completed `property` ¶

all_completed: bool

Whether all items have reached a terminal state.

CompletionDecision `dataclass` ¶

CompletionDecision(
    should_complete: bool,
    completion_reason: CompletionReason | None = None,
)

Decision returned by a completion condition.

Parameters:

Name	Type	Description	Default
`should_complete`	`bool`	Whether the operation should stop collecting results.	required
`completion_reason`	`CompletionReason \| None`	Required when `should_complete` is `True`, and must be `None` when `should_complete` is `False`.	`None`

Raises:

Type	Description
`ValueError`	If `completion_reason` is missing for a complete decision, or present for a continue decision.

Attributes¶

is_succeeded `property` ¶

is_succeeded: bool

Whether this decision completes the operation successfully.

Methods:¶

complete `staticmethod` ¶

complete(
    completion_reason: CompletionReason,
) -> CompletionDecision

Create a decision that completes the operation.

Parameters:

Name	Type	Description	Default
`completion_reason`	`CompletionReason`	Reason to store on the resulting `BatchResult`.	required

Returns:

Type	Description
`CompletionDecision`	A `CompletionDecision` with `should_complete=True`.

continue_execution `staticmethod` ¶

continue_execution() -> CompletionDecision

Create a decision that keeps collecting item or branch results.

Returns:

Type	Description
`CompletionDecision`	A `CompletionDecision` with `should_complete=False`.

NestingType ¶

Bases: Enum

Control how child contexts are created for batch operations.

CompletionConfig `dataclass` ¶

CompletionConfig(
    min_successful: int | None = None,
    tolerated_failure_count: int | None = None,
    should_complete: ShouldComplete | None = None,
)

Configuration for determining when parallel/map operations complete.

Without should_complete, completion is evaluated in this order:

Complete successfully when success_count >= min_successful, if min_successful is configured.
Complete as failed when failure_count > tolerated_failure_count, if tolerated_failure_count is configured.
Complete as failed when tolerated_failure_count is None and at least one failure is observed.
Complete successfully when every item or branch has completed.

If should_complete is configured, it fully controls the completion decision and must return a CompletionDecision.

Parameters:

Name	Type	Description	Default
`min_successful`	`int \| None`	Optional success threshold. Reaching this count completes the operation successfully.	`None`
`tolerated_failure_count`	`int \| None`	Optional failure tolerance. Failures complete the operation as failed only after they exceed this count. When this is `None`, any observed failure fails the operation unless the success threshold has already been reached.	`None`
`should_complete`	`ShouldComplete \| None`	Optional custom completion function. This is mutually exclusive with `min_successful` and `tolerated_failure_count`.	`None`

Raises:

Type	Description
`TypeError`	If `should_complete` is provided but is not callable.
`ValueError`	If `should_complete` is combined with threshold fields.

Attributes¶

has_custom_should_complete `property` ¶

has_custom_should_complete: bool

Whether a custom completion function is configured.

Methods:¶

thresholds `classmethod` ¶

thresholds(
    *,
    min_successful: int | None = None,
    tolerated_failure_count: int | None = None,
) -> CompletionConfig

Create a threshold-based completion configuration.

Parameters:

Name	Type	Description	Default
`min_successful`	`int \| None`	Optional success threshold. The operation completes successfully once this many items or branches succeed.	`None`
`tolerated_failure_count`	`int \| None`	Optional failure tolerance. The operation completes as failed once failures exceed this count.	`None`

Returns:

Type	Description
`CompletionConfig`	A `CompletionConfig` using the supplied threshold fields.

first_successful `classmethod` ¶

first_successful() -> CompletionConfig

Create a configuration that completes after the first success.

Returns:

Type	Description
`CompletionConfig`	A `CompletionConfig` with `min_successful=1` and no explicit failure tolerance. If a failure is observed before any success, the operation completes as failed.

all_completed `classmethod` ¶

all_completed() -> CompletionConfig

Create a configuration with no explicit thresholds.

Returns:

Type	Description
`CompletionConfig`	A `CompletionConfig` with both threshold fields set to `None`. The operation completes successfully when all work completes without failures, and completes as failed when any failure is observed.

all_successful `classmethod` ¶

all_successful() -> CompletionConfig

Create a configuration that requires every item or branch to succeed.

Returns:

Type	Description
`CompletionConfig`	A `CompletionConfig` with `tolerated_failure_count=0`. The first failure exceeds the zero-failure tolerance and completes the operation as failed.

custom `classmethod` ¶

custom(should_complete: ShouldComplete) -> CompletionConfig

Create a configuration that delegates completion to a callback.

Parameters:

Name	Type	Description	Default
`should_complete`	`ShouldComplete`	Deterministic callable that receives a `CompletionStatus` and returns a `CompletionDecision`.	required

Returns:

Type	Description
`CompletionConfig`	A `CompletionConfig` that uses the supplied callback.

completion_decision ¶

completion_decision(
    status: CompletionStatus,
) -> CompletionDecision

Evaluate whether the supplied progress status should complete.

Parameters:

Name	Type	Description	Default
`status`	`CompletionStatus`	Current completion progress for a `map()` or `parallel()` operation.	required

Returns:

Type	Description
`CompletionDecision`	A `CompletionDecision` describing whether execution should continue and, if complete, why.

Raises:

Type	Description
`TypeError`	If a custom completion callback returns `None`.

BatchItemStatus ¶

Bases: Enum

Status of one item or branch inside a batch-style operation.

A CANCELLED item started but did not finish before the parent reached an early completion condition. Its cancellation is stored in the parent BatchResult rather than checkpointed as a child result.

BatchItem `dataclass` ¶

BatchItem(
    index: int,
    status: BatchItemStatus,
    result: R | None = None,
    error: ErrorObject | None = None,
)

Bases: MappingModel, Generic[R]

Result record for one branch or iteration in BatchResult.

BatchResult `dataclass` ¶

BatchResult(
    all: list[BatchItem[R]],
    completion_reason: CompletionReason,
)

Bases: MappingModel, Generic[R]

Aggregated outcome of a map() or parallel() operation.

Functions:¶

parallel ¶

parallel(
    branches: Iterable[Callable[[], Awaitable[T]]],
    *,
    name: str | None = None,
    max_concurrency: int | None = None,
    completion_config: CompletionConfig | None = None,
    serdes: SerDes | None = None,
    item_serdes: SerDes | None = None,
    summary_generator: SummaryGenerator
    | None = ParallelSummaryGenerator(),
    nesting_type: NestingType = NESTED,
) -> Task[BatchResult[T]]

Start a durable parallel operation.

Each branch is an async zero-argument callable, typically a bound durable callable such as fetch_user(user_id). Branches run in child durable contexts and may contain durable operations such as step() or wait().

The returned object is an asyncio.Task; awaiting it yields a BatchResult. Calling parallel() without immediately awaiting it schedules the durable operation in the background, consistent with other operation helpers.

By default, parallel() uses CompletionConfig.all_successful(): every branch must succeed, and the first failure completes the operation as failed. Pass completion_config to use threshold-based or custom completion.

Parameters:

Name	Type	Description	Default
`branches`	`Iterable[Callable[[], Awaitable[T]]]`	Async zero-argument branch callables to run concurrently.	required
`name`	`str \| None`	Optional durable operation name.	`None`
`max_concurrency`	`int \| None`	Optional limit for in-flight branches. A suspended branch retains its slot until it reaches a terminal state.	`None`
`completion_config`	`CompletionConfig \| None`	Optional completion policy. Use `CompletionConfig.thresholds()`, `first_successful()`, `all_completed()`, `all_successful()`, or `custom()`.	`None`
`serdes`	`SerDes \| None`	Optional serializer for the final `BatchResult`.	`None`
`item_serdes`	`SerDes \| None`	Optional serializer for each branch result.	`None`
`summary_generator`	`SummaryGenerator \| None`	Optional callable used to summarize oversized checkpoint payloads.	`ParallelSummaryGenerator()`
`nesting_type`	`NestingType`	Whether branch operations use nested or flat operation identifiers.	`NESTED`

Returns:

Type	Description
`Task[BatchResult[T]]`	An `asyncio.Task` that resolves to a `BatchResult` containing one `BatchItem` per branch.

Raises:

Type	Description
`ValidationError`	If `max_concurrency` is not a positive integer or `None`.
`RuntimeError`	If called outside a durable context.

Parallel¶

Classes¶

CompletionReason ¶

Attributes¶

is_succeeded property ¶

CompletionStatus dataclass ¶

Attributes¶

completed_count property ¶

all_completed property ¶

CompletionDecision dataclass ¶

Attributes¶

is_succeeded property ¶

Methods:¶

complete staticmethod ¶

continue_execution staticmethod ¶

NestingType ¶

CompletionConfig dataclass ¶

Attributes¶

has_custom_should_complete property ¶

Methods:¶

thresholds classmethod ¶

first_successful classmethod ¶

all_completed classmethod ¶

all_successful classmethod ¶

custom classmethod ¶

completion_decision ¶

BatchItemStatus ¶

BatchItem dataclass ¶

BatchResult dataclass ¶

Functions:¶

parallel ¶

is_succeeded `property` ¶

CompletionStatus `dataclass` ¶

completed_count `property` ¶

all_completed `property` ¶

CompletionDecision `dataclass` ¶

is_succeeded `property` ¶

complete `staticmethod` ¶

continue_execution `staticmethod` ¶

CompletionConfig `dataclass` ¶

has_custom_should_complete `property` ¶

thresholds `classmethod` ¶

first_successful `classmethod` ¶

all_completed `classmethod` ¶

all_successful `classmethod` ¶

custom `classmethod` ¶

BatchItem `dataclass` ¶

BatchResult `dataclass` ¶