temporalio.client.WorkflowHandle

class documentation

class WorkflowHandle(Generic[SelfType, ReturnType]): (source)

Known subclasses: temporalio.testing._workflow._TimeSkippingWorkflowHandle

Constructor: WorkflowHandle(client, id, run_id, result_run_id, ...)

Handle for interacting with a workflow.

This is usually created via Client.get_workflow_handle or returned from Client.start_workflow.

Method	`__init__`	Create workflow handle.
Async Method	`cancel`	Cancel the workflow.
Async Method	`describe`	Get workflow details.
Async Method	`execute_update`	Send an update request to the workflow and wait for it to complete.
Async Method	`fetch_history`	Get workflow history.
Method	`fetch_history_events`	Get workflow history events as an async iterator.
Method	`get_update_handle`	Get a handle for an update. The handle can be used to wait on the update result.
Method	`get_update_handle_for`	Get a typed handle for an update. The handle can be used to wait on the update result.
Async Method	`query`	Query the workflow.
Async Method	`result`	Wait for result of the workflow.
Async Method	`signal`	Send a signal to the workflow.
Async Method	`start_update`	Send an update request to the workflow and return a handle to it.
Async Method	`terminate`	Terminate the workflow.
Property	`first_execution_run_id`	Run ID used to ensure requested operations apply to a workflow ID started with this run ID.
Property	`id`	ID for the workflow.
Property	`result_run_id`	Run ID used for `result` calls if present to ensure result is for a workflow starting from this run.
Property	`run_id`	If present, run ID used to ensure that requested operations apply to this exact run.
Method	`_fetch_history_events_for_run`	Undocumented
Async Method	`_start_update`	Undocumented
Instance Variable	`__temporal_eagerly_started`	Undocumented
Instance Variable	`_client`	Undocumented
Instance Variable	`_first_execution_run_id`	Undocumented
Instance Variable	`_id`	Undocumented
Instance Variable	`_result_run_id`	Undocumented
Instance Variable	`_result_type`	Undocumented
Instance Variable	`_run_id`	Undocumented
Instance Variable	`_start_workflow_response`	Undocumented

def __init__(self, client: Client, id: str, *, run_id: str | None = None, result_run_id: str | None = None, first_execution_run_id: str | None = None, result_type: type | None = None, start_workflow_response:

temporalio.api.workflowservice.v1.StartWorkflowExecutionResponse | temporalio.api.workflowservice.v1.SignalWithStartWorkflowExecutionResponse | None

= None): (source) ¶

Create workflow handle.

async def cancel(self, *, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None): (source) ¶

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.

async def describe(self, *, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> WorkflowExecutionDescription: (source) ¶

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.
Returns
`WorkflowExecutionDescription`	Workflow details.
Raises
`RPCError`	Workflow details could not be fetched.

@overload

async def execute_update(self, update: temporalio.workflow.UpdateMethodMultiParam[[SelfType], LocalReturnType], *, id: str | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> LocalReturnType:

@overload

async def execute_update(self, update: temporalio.workflow.UpdateMethodMultiParam[[SelfType, ParamType], LocalReturnType], arg: ParamType, *, id: str | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> LocalReturnType:

@overload

async def execute_update(self, update: temporalio.workflow.UpdateMethodMultiParam[MultiParamSpec, LocalReturnType], *, args: MultiParamSpec.args, id: str | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> LocalReturnType:

@overload

async def execute_update(self, update: str, arg: Any = temporalio.common._arg_unset, *, args: Sequence[Any] = [], id: str | None = None, result_type: type | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> Any:

(source) ¶

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.
Returns
`Any`	Undocumented
Raises
`WorkflowUpdateFailedError`	If the update failed.
`WorkflowUpdateRPCTimeoutOrCancelledError`	This update call timed out or was cancelled. This doesn't mean the update itself was timed out or cancelled.
`RPCError`	There was some issue sending the update to the workflow.

async def fetch_history(self, *, event_filter_type: WorkflowHistoryEventFilterType = WorkflowHistoryEventFilterType.ALL_EVENT, skip_archival: bool = False, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> WorkflowHistory: (source) ¶

Get workflow history.

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

def fetch_history_events(self, *, page_size: int | None = None, next_page_token: bytes | None = None, wait_new_event: bool = False, event_filter_type: WorkflowHistoryEventFilterType = WorkflowHistoryEventFilterType.ALL_EVENT, skip_archival: bool = False, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> WorkflowHistoryEventAsyncIterator: (source) ¶

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.
Returns
`WorkflowHistoryEventAsyncIterator`	An async iterator that doesn't begin fetching until iterated on.

def get_update_handle(self, id: str, *, workflow_run_id: str | None = None, result_type: type | None = None) -> WorkflowUpdateHandle[Any]: (source) ¶

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.
Returns
`WorkflowUpdateHandle[Any]`	The update handle.

def get_update_handle_for(self, update: temporalio.workflow.UpdateMethodMultiParam[Any, LocalReturnType], id: str, *, workflow_run_id: str | None = None) -> WorkflowUpdateHandle[LocalReturnType]: (source) ¶

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.

Parameters
update:`temporalio.workflow.UpdateMethodMultiParam[Any, LocalReturnType]`	The update method to use for typing the handle.
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.
Returns
`WorkflowUpdateHandle[LocalReturnType]`	The update handle.

@overload

async def query(self, query: MethodSyncOrAsyncNoParam[SelfType, LocalReturnType], *, reject_condition: temporalio.common.QueryRejectCondition | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> LocalReturnType:

@overload

async def query(self, query: MethodSyncOrAsyncSingleParam[SelfType, ParamType, LocalReturnType], arg: ParamType, *, reject_condition: temporalio.common.QueryRejectCondition | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> LocalReturnType:

@overload

async def query(self, query: Callable[Concatenate[SelfType, MultiParamSpec], Awaitable[LocalReturnType] | LocalReturnType], *, args: Sequence[Any], reject_condition: temporalio.common.QueryRejectCondition | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> LocalReturnType:

@overload

async def query(self, query: str, arg: Any = temporalio.common._arg_unset, *, args: Sequence[Any] = [], result_type: type | None = None, reject_condition: temporalio.common.QueryRejectCondition | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> Any:

(source) ¶

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.
Raises
`WorkflowQueryRejectedError`	A query reject condition was satisfied.
`RPCError`	Workflow details could not be fetched.

async def result(self, *, follow_runs: bool = True, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> ReturnType: (source) ¶

overridden in temporalio.testing._workflow._TimeSkippingWorkflowHandle

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.
Raises
`WorkflowFailureError`	Workflow failed, was cancelled, was terminated, or timed out. Use the `WorkflowFailureError.cause` to see the underlying reason.
`Exception`	Other possible failures during result fetching.

@overload

async def signal(self, signal: MethodSyncOrAsyncNoParam[SelfType, None], *, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None):

@overload

async def signal(self, signal: MethodSyncOrAsyncSingleParam[SelfType, ParamType, None], arg: ParamType, *, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None):

@overload

async def signal(self, signal: Callable[Concatenate[SelfType, MultiParamSpec], Awaitable[None] | None], *, args: Sequence[Any], rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None):

@overload

async def signal(self, signal: str, arg: Any = temporalio.common._arg_unset, *, args: Sequence[Any] = [], rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None):

(source) ¶

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.

@overload

async def start_update(self, update: temporalio.workflow.UpdateMethodMultiParam[[SelfType], LocalReturnType], *, wait_for_stage: WorkflowUpdateStage, id: str | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> WorkflowUpdateHandle[LocalReturnType]:

@overload

async def start_update(self, update: temporalio.workflow.UpdateMethodMultiParam[[SelfType, ParamType], LocalReturnType], arg: ParamType, *, wait_for_stage: WorkflowUpdateStage, id: str | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> WorkflowUpdateHandle[LocalReturnType]:

@overload

async def start_update(self, update: temporalio.workflow.UpdateMethodMultiParam[MultiParamSpec, LocalReturnType], *, args: MultiParamSpec.args, wait_for_stage: WorkflowUpdateStage, id: str | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> WorkflowUpdateHandle[LocalReturnType]:

@overload

async def start_update(self, update: str, arg: Any = temporalio.common._arg_unset, *, wait_for_stage: WorkflowUpdateStage, args: Sequence[Any] = [], id: str | None = None, result_type: type | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> WorkflowUpdateHandle[Any]:

(source) ¶

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.
Returns
`WorkflowUpdateHandle[Any]`	Undocumented
Raises
`WorkflowUpdateRPCTimeoutOrCancelledError`	This update call timed out or was cancelled. This doesn't mean the update itself was timed out or cancelled.
`RPCError`	There was some issue sending the update to the workflow.

async def terminate(self, *args: Any, reason: str | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None): (source) ¶

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.

@property
first_execution_run_id: str | None = (source) ¶

Run ID used to ensure requested operations apply to a workflow ID started with this run ID.

This can be set when using Client.get_workflow_handle. When Client.start_workflow is called without a start signal, this is set to the resulting run.

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

@property
id: str = (source) ¶

ID for the workflow.

@property
result_run_id: str | None = (source) ¶

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.

@property
run_id: str | None = (source) ¶

If present, run ID used to ensure that requested operations apply to this exact run.

This is only created via Client.get_workflow_handle. Client.start_workflow will not set this value.

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

def _fetch_history_events_for_run(self, run_id: str | None, *, page_size: int | None = None, next_page_token: bytes | None = None, wait_new_event: bool = False, event_filter_type: WorkflowHistoryEventFilterType = WorkflowHistoryEventFilterType.ALL_EVENT, skip_archival: bool = False, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> WorkflowHistoryEventAsyncIterator: (source) ¶

Undocumented

async def _start_update(self, update: str | Callable, arg: Any = temporalio.common._arg_unset, *, wait_for_stage: WorkflowUpdateStage, args: Sequence[Any] = [], id: str | None = None, result_type: type | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> WorkflowUpdateHandle[Any]: (source) ¶

Undocumented

__temporal_eagerly_started: bool = (source) ¶

Undocumented

_client = (source) ¶

Undocumented

_first_execution_run_id = (source) ¶

Undocumented

_id = (source) ¶

Undocumented

_result_run_id = (source) ¶

Undocumented

_result_type = (source) ¶

Undocumented

_run_id = (source) ¶

Undocumented

_start_workflow_response = (source) ¶

Undocumented