Client¶
Async client for the Durable Workflow server's control and worker planes.
The :class:Client wraps the server's HTTP/JSON protocol. Control-plane
methods (start_workflow, signal_workflow, describe_workflow,
schedule management, …) are what callers use to drive workflows from outside.
Worker-plane methods (register_worker, poll_workflow_task,
complete_activity_task, …) are what the :class:~durable_workflow.Worker
uses to run tasks; they are public so advanced users can build custom
workers, but most applications should not call them directly.
The module also defines the returned-value dataclasses (WorkflowExecution,
WorkflowList, ScheduleSpec, ScheduleDescription, …) and the
ergonomic handle classes (:class:WorkflowHandle, :class:ScheduleHandle)
that bind a workflow or schedule id to a :class:Client so you can call
methods without repeating the id on every call.
dataclass
¶
WorkflowExecution(workflow_id, run_id, workflow_type, status=None, namespace=None, task_queue=None, input=None, output=None, payload_codec=None)
Current server view of one workflow execution.
dataclass
¶
One page of workflow visibility results.
dataclass
¶
Calendar or interval rules for a scheduled workflow.
dataclass
¶
ScheduleAction(workflow_type, task_queue=None, input=None, execution_timeout_seconds=None, run_timeout_seconds=None)
Workflow start request issued whenever a schedule fires.
dataclass
¶
ScheduleDescription(schedule_id, status=None, spec=None, action=None, overlap_policy=None, note=None, memo=None, search_attributes=None, jitter_seconds=None, max_runs=None, remaining_actions=None, fires_count=0, failures_count=0, next_fire_at=None, last_fired_at=None, latest_workflow_instance_id=None, paused_at=None, created_at=None, updated_at=None, info=None)
Current server view of a schedule and its recent execution state.
dataclass
¶
One page of schedule visibility results.
dataclass
¶
ScheduleTriggerResult(schedule_id, outcome, workflow_id=None, run_id=None, reason=None, buffer_depth=None)
Outcome returned after manually triggering a schedule.
dataclass
¶
Outcome returned after asking a schedule to backfill missed fires.
Convenience wrapper for operating on one workflow ID.
async
¶
Block until this workflow terminates and return its result. See :meth:Client.get_result.
async
¶
Return the server's current view of this workflow. See :meth:Client.describe_workflow.
async
¶
Deliver an external signal to this workflow. See :meth:Client.signal_workflow.
async
¶
Execute a read-only query against this workflow. See :meth:Client.query_workflow.
async
¶
Request graceful cancellation of this workflow. See :meth:Client.cancel_workflow.
async
¶
Forcefully stop this workflow. See :meth:Client.terminate_workflow.
async
¶
Send a synchronous update to this workflow and wait for the result. See :meth:Client.update_workflow.
Convenience wrapper for operating on one schedule ID.
async
¶
Return the server's current view of this schedule. See :meth:Client.describe_schedule.
async
¶
update(*, spec=None, action=None, overlap_policy=None, jitter_seconds=None, max_runs=None, memo=None, search_attributes=None, note=None)
Update one or more fields of this schedule. See :meth:Client.update_schedule.
async
¶
Pause this schedule so it stops firing. See :meth:Client.pause_schedule.
async
¶
Fire this schedule immediately. See :meth:Client.trigger_schedule.
async
¶
Fire this schedule for every moment in a past time range. See :meth:Client.backfill_schedule.
Client(base_url, *, token=None, control_token=None, worker_token=None, namespace='default', timeout=60.0, retry_policy=None, metrics=None)
Async HTTP client for Durable Workflow control-plane and worker APIs.
The client owns one httpx.AsyncClient connection pool. Use it as an async
context manager or call aclose() when finished.
async
¶
Close the underlying httpx connection pool.
Equivalent to exiting the async-context-manager form of the client. Safe to call multiple times.
async
¶
Fetch server build identity, capabilities, and protocol manifests.
Return a :class:WorkflowHandle bound to an existing workflow instance.
Does not round-trip to the server. Pass run_id to pin the handle to
a specific run, otherwise the handle resolves to whichever run is
current at the time each method is called. workflow_type is
optional and used only in error messages.
async
¶
start_workflow(*, workflow_type, task_queue, workflow_id, input=None, execution_timeout_seconds=3600, run_timeout_seconds=600, duplicate_policy=None, memo=None, search_attributes=None)
Start a new workflow instance and return a handle bound to it.
workflow_type is the language-neutral type key registered via
:func:durable_workflow.workflow.defn. task_queue selects which
worker pool picks up the workflow. workflow_id is the
caller-supplied instance id — if it collides with an existing
workflow, behavior depends on duplicate_policy
(reject | allow | terminate_existing).
input is a list of positional arguments passed to the workflow's
run method; the SDK encodes the list with the default payload
codec (Avro). execution_timeout_seconds covers the entire workflow
execution across all runs (including continue-as-new), while
run_timeout_seconds applies to this single run only.
memo and search_attributes attach operator-facing metadata to
the instance; see the main docs site for the key/value rules.
async
¶
Return the server's current view of a workflow instance.
Resolves to the newest durable run in the instance's chain (including
any continue-as-new runs). Decodes the recorded input and
output envelopes when present.
async
¶
list_workflows(*, workflow_type=None, status=None, query=None, page_size=None, next_page_token=None)
Page through workflow instances, optionally filtered by type, status, or query string.
Pass the returned :attr:WorkflowList.next_page_token as
next_page_token on the next call to fetch the following page; the
token is None when there are no more pages.
async
¶
Fetch the full durable history for one specific run of a workflow.
async
¶
Deliver an external signal to a running workflow.
Signals are fire-and-forget: the server records the signal in durable history and returns immediately. They do not wait for the workflow to observe the signal. See the main docs for how to declare the allowed signal names on a workflow type.
async
¶
Execute a named read-only query against a workflow and return the result.
Queries are synchronous and non-mutating. The server runs the named
query handler inside the workflow process and returns the decoded
result. Raises :class:~durable_workflow.errors.QueryFailed if the
query was rejected or the handler errored.
async
¶
Request graceful cancellation of a workflow's current run.
Cancellation is cooperative: the server delivers a cancellation signal
that the workflow can observe and handle (e.g. to roll back via a
saga). Compare with :meth:terminate_workflow, which is forceful.
async
¶
Forcefully stop a workflow without giving it a chance to clean up.
Prefer :meth:cancel_workflow when the workflow code can implement
graceful shutdown. Termination is an operator escape hatch.
async
¶
update_workflow(workflow_id, update_name, *, args=None, wait_for=None, wait_timeout_seconds=None, request_id=None)
Send a synchronous update to a running workflow and wait for the result.
Updates are request/response calls to a named handler on the workflow;
the handler may mutate durable workflow state and return a value.
wait_for selects how long the server waits before returning —
typically completed to block until the handler finishes, or
accepted to return once the validator has approved it.
request_id lets the caller deduplicate retries. Raises
:class:~durable_workflow.errors.UpdateRejected when the workflow's
validator rejects the update.
async
¶
Poll a workflow until it reaches a terminal state and return its result.
Raises :class:~durable_workflow.errors.WorkflowFailed,
:class:~durable_workflow.errors.WorkflowCancelled, or
:class:~durable_workflow.errors.WorkflowTerminated if the workflow
ended in a non-success state, or :class:TimeoutError if timeout
seconds elapse before the workflow terminates.
Return a :class:ScheduleHandle bound to an existing schedule.
Does not round-trip to the server. Use :meth:describe_schedule via
the handle when you need to verify the schedule actually exists.
async
¶
create_schedule(*, schedule_id=None, spec, action, overlap_policy=None, jitter_seconds=None, max_runs=None, memo=None, search_attributes=None, paused=False, note=None)
Create a new schedule and return a handle bound to it.
spec describes when the schedule fires (cron expressions,
intervals, calendars); action describes what it starts (typically
a workflow). overlap_policy controls what happens when a fire
would overlap an already-running action — skip, buffer_one,
buffer_all, cancel_other, or terminate_other. Pass
paused=True to create the schedule in a paused state and resume
it later with :meth:resume_schedule.
async
¶
Return the server's current view of a schedule, including status and fire counters.
async
¶
update_schedule(schedule_id, *, spec=None, action=None, overlap_policy=None, jitter_seconds=None, max_runs=None, memo=None, search_attributes=None, note=None)
Update one or more fields of an existing schedule.
Pass None for any field you don't want to change. Unknown fields
are ignored by the server.
async
¶
Pause a schedule so it stops firing until resumed.
Optional note is recorded as operator metadata on the pause
event. Pausing does not cancel workflows that are already running.
async
¶
Resume a paused schedule so it begins firing again.
async
¶
Fire a schedule immediately, outside its normal schedule.
The overlap_policy override applies only to this one manual fire.
The returned :class:ScheduleTriggerResult reports whether the fire
was accepted or skipped (e.g. due to overlap).
async
¶
Delete a schedule. Running workflows the schedule already started are unaffected.
async
¶
Fire a schedule for every would-have-been moment in [start_time, end_time].
Times are ISO-8601 strings. Useful to replay a period the schedule
was paused or to seed historical runs. The returned
:class:ScheduleBackfillResult reports how many fires were attempted
and the outcome of each.
async
¶
register_worker(*, worker_id, task_queue, supported_workflow_types=None, supported_activity_types=None, runtime='python', sdk_version=None)
Register this process with the server as a worker for task_queue.
Called by :class:~durable_workflow.Worker at startup. Most
applications should not call this directly — create a
:class:~durable_workflow.Worker instead.
async
¶
Long-poll for the next workflow task on task_queue.
Returns the task payload, or None on poll timeout. Worker-plane
endpoint — most applications use :class:~durable_workflow.Worker
rather than calling this directly.
async
¶
Report successful execution of a workflow task with its emitted commands.
Worker-plane endpoint, called by :class:~durable_workflow.Worker.
commands is the list of serialized commands the workflow yielded
for this task.
async
¶
fail_workflow_task(*, task_id, lease_owner, workflow_task_attempt, message, failure_type=None, stack_trace=None)
Report a workflow task failure so the server can schedule a retry.
Worker-plane endpoint. Task failures (e.g. non-determinism) are
distinct from workflow failures (FailWorkflow commands).
async
¶
Page through extra history events while the worker is executing a long task.
Worker-plane endpoint. The first page of history is delivered inline with the workflow task; this endpoint fetches subsequent pages.
async
¶
Long-poll for the next activity task on task_queue.
Returns the task payload, or None on poll timeout. Worker-plane
endpoint — typically used by :class:~durable_workflow.Worker.
async
¶
complete_activity_task(*, task_id, activity_attempt_id, lease_owner, result, codec=serializer.AVRO_CODEC)
Report successful activity execution and submit the encoded result.
async
¶
fail_activity_task(*, task_id, activity_attempt_id, lease_owner, message, failure_type=None, stack_trace=None, non_retryable=False, details=None, codec=serializer.AVRO_CODEC)
Report a failed activity attempt.
Pass non_retryable=True to signal that this class of error will
not be fixed by retrying — the server then surfaces the failure to
the workflow immediately instead of scheduling another attempt.
async
¶
Send a liveness heartbeat for a running activity attempt.
Worker-plane endpoint. Most code calls
:meth:~durable_workflow.ActivityContext.heartbeat instead, which
additionally raises :class:~durable_workflow.errors.ActivityCancelled
when the server reports the activity should stop.