class Workflow[P, A, E]
A durable workflow taking a P payload, succeeding with A and
failing with E. Make one with make.
Attributes#
| Attribute | Type | Description |
|---|---|---|
tag | str | 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_key | Callable[[P], str] | The key of a payload: executions with the same key are one execution. |
annotations | Context[Any] | The workflow's annotations. |
suspended_retry_schedule | Schedule[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| Parameter | Type | Description |
|---|---|---|
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 |
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_scheduleannotate#
annotate[S, T](tag, value) -> Workflow[P, A, E]A copy with tag annotated (SuspendOnFailure, ...).
| Parameter | Type | Description |
|---|---|---|
tag | TagLike[S, T] | |
value | S |
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]| Parameter | Type | Description |
|---|---|---|
annotations | Context[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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
execution_id | str |
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.
| Parameter | Type | Description |
|---|---|---|
execution_id | str |
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).
| Parameter | Type | Description |
|---|---|---|
execution_id | str |
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
payload | P |
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.
| Parameter | Type | Description |
|---|---|---|
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])