temporalio.client.WorkflowHandle

Cancel the workflow.

This will issue a cancellation for run_id if present. This call will make sure to use the run chain starting from first_execution_run_id if present. To create handles with these values, use Client.get_workflow_handle.

Warning

Handles created as a result of Client.start_workflow with a start signal will cancel the latest workflow with the same workflow ID even if it is unrelated to the started workflow.

Parameters
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for the RPC call.

Raises
`RPCError`	Workflow could not be cancelled.

Get workflow details.

This will get details for run_id if present. To use a different run ID, create a new handle with via Client.get_workflow_handle.

Warning

Handles created as a result of Client.start_workflow will describe the latest workflow with the same workflow ID even if it is unrelated to the started workflow.

Parameters
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for the RPC call.

Raises
`RPCError`	Workflow details could not be fetched.

Send an update request to the workflow and wait for it to complete.

This will target the workflow with run_id if present. To use a different run ID, create a new handle with via Client.get_workflow_handle.

Parameters
update:`str \| Callable`	Update function or name on the workflow.
arg:`Any`	Single argument to the update.
args:`Sequence[Any]`	Multiple arguments to the update. Cannot be set if arg is.
id:`str \| None`	ID of the update. If not set, the default is a new UUID.
result_type:`type \| None`	For string updates, this can set the specific result type hint to deserialize into.
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for the RPC call.

Get workflow history.

This is a shortcut for fetch_history_events that just fetches all events.

Get workflow history events as an async iterator.

This does not make a request until the first iteration is attempted. Therefore any errors will not occur until then.

Parameters
page_size:`int \| None`	Maximum amount to fetch per request if any maximum.
next_page_token:`bytes \| None`	A specific page token to fetch.
wait_new_event:`bool`	Whether the event fetching request will wait for new events or just return right away.
event_filter_type:`WorkflowHistoryEventFilterType`	Which events to obtain.
skip_archival:`bool`	Whether to skip archival.
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on each RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for each RPC call.

Get a handle for an update. The handle can be used to wait on the update result.

Users may prefer the more typesafe get_update_handle_for which accepts an update definition.

Parameters
id:`str`	Update ID to get a handle to.
workflow_run_id:`str \| None`	Run ID to tie the handle to. If this is not set, the `run_id` will be used.
result_type:`type \| None`	The result type to deserialize into if known.

Get a typed handle for an update. The handle can be used to wait on the update result.

This is the same as get_update_handle but typed.

Query the workflow.

This will query for run_id if present. To use a different run ID, create a new handle with Client.get_workflow_handle.

Warning

Handles created as a result of Client.start_workflow will query the latest workflow with the same workflow ID even if it is unrelated to the started workflow.

Parameters
query:`str \| Callable`	Query function or name on the workflow.
arg:`Any`	Single argument to the query.
args:`Sequence[Any]`	Multiple arguments to the query. Cannot be set if arg is.
result_type:`type \| None`	For string queries, this can set the specific result type hint to deserialize into.
reject_condition:`temporalio.common.QueryRejectCondition \| None`	Condition for rejecting the query. If unset/None, defaults to the client's default (which is defaulted to None).
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for the RPC call.

Returns
`Any`	Result of the query.

Wait for result of the workflow.

This will use result_run_id if present to base the result on. To use another run ID, a new handle must be created via Client.get_workflow_handle.

Parameters
follow_runs:`bool`	If true (default), workflow runs will be continually fetched, until the most recent one is found. If false, return the result from the first run targeted by the request if that run ends in a result, otherwise raise an exception.
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for each RPC call. Note, this is the timeout for each history RPC call not this overall function.

Returns
`ReturnType`	Result of the workflow after being converted by the data converter.

Send a signal to the workflow.

This will signal for run_id if present. To use a different run ID, create a new handle with via Client.get_workflow_handle.

Warning

Handles created as a result of Client.start_workflow will signal the latest workflow with the same workflow ID even if it is unrelated to the started workflow.

Parameters
signal:`str \| Callable`	Signal function or name on the workflow.
arg:`Any`	Single argument to the signal.
args:`Sequence[Any]`	Multiple arguments to the signal. Cannot be set if arg is.
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for the RPC call.

Raises
`RPCError`	Workflow could not be signalled.

Send an update request to the workflow and return a handle to it.

This will target the workflow with run_id if present. To use a different run ID, create a new handle with via Client.get_workflow_handle.

Parameters
update:`str \| Callable`	Update function or name on the workflow. arg: Single argument to the update.
arg:`Any`	Undocumented
wait_for_stage:`WorkflowUpdateStage`	Required stage to wait until returning: either ACCEPTED or COMPLETED. ADMITTED is not currently supported. See https://docs.temporal.io/workflows#update for more details.
args:`Sequence[Any]`	Multiple arguments to the update. Cannot be set if arg is.
id:`str \| None`	ID of the update. If not set, the default is a new UUID.
result_type:`type \| None`	For string updates, this can set the specific result type hint to deserialize into.
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for the RPC call.

Terminate the workflow.

This will issue a termination for run_id if present. This call will make sure to use the run chain starting from first_execution_run_id if present. To create handles with these values, use Client.get_workflow_handle.

Warning

Handles created as a result of Client.start_workflow with a start signal will terminate the latest workflow with the same workflow ID even if it is unrelated to the started workflow.

Parameters
*args:`Any`	Details to store on the termination.
reason:`str \| None`	Reason for the termination.
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for the RPC call.

Raises
`RPCError`	Workflow could not be terminated.

Run ID used for result calls if present to ensure result is for a workflow starting from this run.

When this handle is created via Client.get_workflow_handle, this is the same as run_id. When this handle is created via Client.start_workflow, this value will be the resulting run ID.

This cannot be mutated. If a different run ID is needed, Client.get_workflow_handle must be used instead.