GitHub

Workflow

API reference for Workflow.

class Workflow[P, A, E]

A durable workflow taking a P payload, succeeding with A and failing with E. Make one with make.

Attributes

AttributeTypeDescription
tagstr

The workflow's name.

payload_schema_C[P]

The schema of the workflow's payload.

success_schema_C[A]

The schema of the workflow's success.

error_schema_C[E]

The schema of the workflow's failure.

idempotency_keyCallable[[P], str]

The key of a payload: executions with the same key are one execution.

annotationsContext[Any]

The workflow's annotations.

suspended_retry_scheduleSchedule[Any, Any, Any, Any] | None

How a suspended execution is retried, when set.

Functions

__init__

__init__(tag, *, payload_schema, success_schema, error_schema, idempotency_key, annotations, suspended_retry_schedule) -> None
ParameterTypeDescription
tagstr
payload_schema_C[P]
success_schema_C[A]
error_schema_C[E]
idempotency_keyCallable[[P], str]
annotationsContext[Any]
suspended_retry_scheduleSchedule[Any, Any, Any, Any] | None
def __init__(
    self,
    tag: str,
    *,
    payload_schema: _C[P],
    success_schema: _C[A],
    error_schema: _C[E],
    idempotency_key: Callable[[P], str],
    annotations: Context[Any],
    suspended_retry_schedule: Schedule[Any, Any, Any, Any] | None,
) -> None:
    self._tag = tag
    self._payload_schema = payload_schema
    self._success_schema = success_schema
    self._error_schema = error_schema
    self._idempotency_key = idempotency_key
    self._annotations = annotations
    self._suspended_retry_schedule = suspended_retry_schedule

annotate

annotate[S, T](tag, value) -> Workflow[P, A, E]

A copy with tag annotated (SuspendOnFailure, ...).

ParameterTypeDescription
tagTagLike[S, T]
valueS

Returns Workflow[P, A, E]

def annotate[S, T](self, tag: TagLike[S, T], value: S) -> Workflow[P, A, E]:
    """A copy with ``tag`` annotated (``SuspendOnFailure``, ...)."""
    return self._with_annotations(self.annotations.add(tag, value))

annotate_merge

annotate_merge(annotations) -> Workflow[P, A, E]
ParameterTypeDescription
annotationsContext[Any]

Returns Workflow[P, A, E]

def annotate_merge(self, annotations: Context[Any]) -> Workflow[P, A, E]:
    return self._with_annotations(self.annotations.merge(annotations))

execute

execute(payload: P, *, discard: Literal[True], detached: bool = False) -> Effect[str, Never, WorkflowEngine]
execute(payload: P, *, discard: Literal[False] = False) -> Effect[A, E, WorkflowEngine]

Run the workflow with payload and wait for its result. A caller outside any workflow retries a suspended execution on the workflow's suspended_retry_schedule.

discard=True gives the execution id without waiting; the child stays linked to its parent workflow for completion wakes and interruption, unless detached=True too. Do not wait for a detached execution later: executing the same payload joins it, but its completion does not wake the waiting workflow.

ParameterTypeDescription
payload
discard= False
detached= False
@overload
def execute(
    self, payload: P, *, discard: Literal[True], detached: bool = False
) -> Effect[str, Never, WorkflowEngine]: ...
@overload
def execute(
    self, payload: P, *, discard: Literal[False] = False
) -> Effect[A, E, WorkflowEngine]: ...
def execute(
    self, payload: P, *, discard: bool = False, detached: bool = False
) -> Effect[Any, Any, WorkflowEngine]:
    """Run the workflow with ``payload`` and wait for its result. A
    caller outside any workflow retries a suspended execution on the
    workflow's ``suspended_retry_schedule``.

    ``discard=True`` gives the execution id without waiting; the child
    stays linked to its parent workflow for completion wakes and
    interruption, unless ``detached=True`` too. Do not wait for a
    detached execution later: executing the same payload joins it,
    but its completion does not wake the waiting workflow."""

    def body() -> Effect[Any, Any, WorkflowEngine]:
        made = self.payload_schema.__codec__().make(payload)

        def run_on(execution_id: str) -> Effect[Any, Any, WorkflowEngine]:
            return annotate_current_span("executionId", execution_id).and_then(
                WorkflowEngine().flat_map(
                    lambda engine: engine.execute(
                        self,
                        execution_id=execution_id,
                        payload=made,
                        discard=discard,
                        detached=detached,
                        suspended_retry_schedule=self.suspended_retry_schedule,
                    )
                )
            )

        run = suspend_effect(lambda: self._execution_id_of(made)).flat_map(run_on)
        # Count the child with its parent before its id is computed, so
        # a sibling that suspends first waits for it to be dispatched.
        return run if discard else with_pending_activity(run)

    return suspend_effect(body).with_span(f"{self.tag}.execute", capture_stack_trace=False)

poll

poll(execution_id) -> Effect[Result[A, E] | None, Never, WorkflowEngine]

The result of the execution so far: None while it has none.

ParameterTypeDescription
execution_idstr

Returns Effect[Result[A, E] | None, Never, WorkflowEngine]

def poll(self, execution_id: str) -> Effect[Result[A, E] | None, Never, WorkflowEngine]:
    """The result of the execution so far: ``None`` while it has none."""
    return (
        WorkflowEngine()
        .flat_map(lambda engine: engine.poll(self, execution_id))
        .with_span(
            f"{self.tag}.poll",
            attributes={"executionId": execution_id},
            capture_stack_trace=False,
        )
    )

interrupt

interrupt(execution_id) -> Effect[None, Never, WorkflowEngine]

Interrupt the execution: it ends at its next suspension, running its compensations and finalizers.

ParameterTypeDescription
execution_idstr

Returns Effect[None, Never, WorkflowEngine]

def interrupt(self, execution_id: str) -> Effect[None, Never, WorkflowEngine]:
    """Interrupt the execution: it ends at its next suspension, running
    its compensations and finalizers."""
    return (
        WorkflowEngine()
        .flat_map(lambda engine: engine.interrupt(self, execution_id))
        .with_span(
            f"{self.tag}.interrupt",
            attributes={"executionId": execution_id},
            capture_stack_trace=False,
        )
    )

resume

resume(execution_id) -> Effect[None, Never, WorkflowEngine]

Replay a suspended execution (also one suspended by SuspendOnFailure).

ParameterTypeDescription
execution_idstr

Returns Effect[None, Never, WorkflowEngine]

def resume(self, execution_id: str) -> Effect[None, Never, WorkflowEngine]:
    """Replay a suspended execution (also one suspended by
    ``SuspendOnFailure``)."""
    return (
        WorkflowEngine()
        .flat_map(lambda engine: engine.resume(self, execution_id))
        .with_span(
            f"{self.tag}.resume",
            attributes={"executionId": execution_id},
            capture_stack_trace=False,
        )
    )

to_layer

to_layer[A2, E2](execute: Callable[[P, str], Effect[A2, E2, WorkflowEngine | WorkflowInstance | Scope]]) -> Layer[Never, Never, WorkflowEngine]
to_layer[A2, E2, R](execute: Callable[[P, str], Effect[A2, E2, R | WorkflowEngine | WorkflowInstance | Scope]]) -> Layer[Never, Never, R | WorkflowEngine]

The layer registering execute(payload, execution_id) as the workflow's handler; it runs with the layer's services.

ParameterTypeDescription
execute
@overload
def to_layer[A2, E2](
    self: Workflow[P, A2, E2],
    execute: Callable[[P, str], Effect[A2, E2, WorkflowEngine | WorkflowInstance | Scope]],
) -> Layer[Never, Never, WorkflowEngine]: ...
@overload
def to_layer[A2, E2, R](
    self: Workflow[P, A2, E2],
    execute: Callable[[P, str], Effect[A2, E2, R | WorkflowEngine | WorkflowInstance | Scope]],
) -> Layer[Never, Never, R | WorkflowEngine]: ...
def to_layer[A2, E2, R](
    self: Workflow[P, A2, E2],
    execute: Callable[[P, str], Effect[A2, E2, R | WorkflowEngine | WorkflowInstance | Scope]],
) -> Layer[Never, Never, R | WorkflowEngine]:
    """The layer registering ``execute(payload, execution_id)`` as the
    workflow's handler; it runs with the layer's services."""
    return effect_discard(
        WorkflowEngine().flat_map(lambda engine: engine.register(self, execute))
    )

execution_id

execution_id(payload) -> Effect[str]

The execution id payload runs under.

ParameterTypeDescription
payloadP

Returns Effect[str]

def execution_id(self, payload: P) -> Effect[str]:
    """The execution id ``payload`` runs under."""
    return suspend_effect(
        lambda: self._execution_id_of(self.payload_schema.__codec__().make(payload))
    )

with_compensation

with_compensation[B, EB, RB, R2 = Never](effect: Effect[B, EB, RB], compensation: Callable[[B, Cause[E]], Effect[object, Never, R2]], /) -> Effect[B, EB, RB | R2 | WorkflowInstance | Scope]
with_compensation[R2 = Never](compensation: Callable[[Any, Cause[E]], Effect[object, Never, R2]], /) -> _Compensate[R2]

with_compensation(effect, compensation) (or curried, for .pipe): when the whole workflow fails, run compensation(value, cause) with effect's value. Only top-level steps of the workflow are compensated, not effects nested inside an activity.

ParameterTypeDescription
args= ()
@overload
def with_compensation[B, EB, RB, R2 = Never](
    self,
    effect: Effect[B, EB, RB],
    compensation: Callable[[B, Cause[E]], Effect[object, Never, R2]],
    /,
) -> Effect[B, EB, RB | R2 | WorkflowInstance | Scope]: ...
@overload
def with_compensation[R2 = Never](
    self, compensation: Callable[[Any, Cause[E]], Effect[object, Never, R2]], /
) -> _Compensate[R2]: ...
def with_compensation(self, *args: Any) -> Any:
    """``with_compensation(effect, compensation)`` (or curried, for
    ``.pipe``): when the whole workflow fails, run
    ``compensation(value, cause)`` with ``effect``'s value. Only
    top-level steps of the workflow are compensated, not effects
    nested inside an activity."""
    if len(args) == 2:
        return with_compensation(args[0], args[1])
    return _Compensate(args[0])