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

def __init__(self, client: Client, id: str, *, run_id: Optional[str] = None, result_run_id: Optional[str] = None, first_execution_run_id: Optional[str] = None, result_type: Optional[Type] = None): (source) ¶

Create workflow handle.

async def cancel(self, *, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = 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]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`Optional[timedelta]`	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] = {}, rpc_timeout: Optional[timedelta] = 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]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`Optional[timedelta]`	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: Optional[str] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = None) -> LocalReturnType:

@overload

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

@overload

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

@overload

async def execute_update(self, update: str, arg: Any = temporalio.common._arg_unset, *, args: Sequence[Any] = [], id: Optional[str] = None, result_type: Optional[Type] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = 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.

Warning

This API is experimental

Parameters
update:`Union[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:`Optional[str]`	ID of the update. If not set, the default is a new UUID.
result_type:`Optional[Type]`	For string updates, this can set the specific result type hint to deserialize into.
rpc_metadata:`Mapping[str, str]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`Optional[timedelta]`	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] = {}, rpc_timeout: Optional[timedelta] = 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: Optional[int] = None, next_page_token: Optional[bytes] = None, wait_new_event: bool = False, event_filter_type: WorkflowHistoryEventFilterType = WorkflowHistoryEventFilterType.ALL_EVENT, skip_archival: bool = False, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = 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:`Optional[int]`	Maximum amount to fetch per request if any maximum.
next_page_token:`Optional[bytes]`	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]`	Headers used on each RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`Optional[timedelta]`	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: Optional[str] = None, result_type: Optional[Type] = 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.

Warning

This API is experimental

Parameters
id:`str`	Update ID to get a handle to.
workflow_run_id:`Optional[str]`	Run ID to tie the handle to. If this is not set, the `run_id` will be used.
result_type:`Optional[Type]`	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: Optional[str] = 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.

Warning

This API is experimental

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:`Optional[str]`	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: Optional[temporalio.common.QueryRejectCondition] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = None) -> LocalReturnType:

@overload

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

@overload

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

@overload

async def query(self, query: str, arg: Any = temporalio.common._arg_unset, *, args: Sequence[Any] = [], result_type: Optional[Type] = None, reject_condition: Optional[temporalio.common.QueryRejectCondition] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = 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 via 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:`Union[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:`Optional[Type]`	For string queries, this can set the specific result type hint to deserialize into.
reject_condition:`Optional[temporalio.common.QueryRejectCondition]`	Condition for rejecting the query. If unset/None, defaults to the client's default (which is defaulted to None).
rpc_metadata:`Mapping[str, str]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`Optional[timedelta]`	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] = {}, rpc_timeout: Optional[timedelta] = 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, the first result is used.
rpc_metadata:`Mapping[str, str]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`Optional[timedelta]`	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] = {}, rpc_timeout: Optional[timedelta] = None):

@overload

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

@overload

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

@overload

async def signal(self, signal: str, arg: Any = temporalio.common._arg_unset, *, args: Sequence[Any] = [], rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = 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:`Union[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]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`Optional[timedelta]`	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: Optional[str] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = None) -> WorkflowUpdateHandle[LocalReturnType]:

@overload

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

@overload

async def start_update(self, update: temporalio.workflow.UpdateMethodMultiParam[MultiParamSpec, LocalReturnType], *, args: MultiParamSpec.args, wait_for_stage: WorkflowUpdateStage, id: Optional[str] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = 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: Optional[str] = None, result_type: Optional[Type] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = 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.

Warning

This API is experimental

Parameters
update:`Union[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:`Optional[str]`	ID of the update. If not set, the default is a new UUID.
result_type:`Optional[Type]`	For string updates, this can set the specific result type hint to deserialize into.
rpc_metadata:`Mapping[str, str]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`Optional[timedelta]`	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: Optional[str] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = 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:`Optional[str]`	Reason for the termination.
rpc_metadata:`Mapping[str, str]`	Headers used on the RPC call. Keys here override client-level RPC metadata keys.
rpc_timeout:`Optional[timedelta]`	Optional RPC deadline to set for the RPC call.
Raises
`RPCError`	Workflow could not be terminated.

@property
first_execution_run_id: Optional[str] = (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: Optional[str] = (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: Optional[str] = (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: Optional[str], *, page_size: Optional[int] = None, next_page_token: Optional[bytes] = None, wait_new_event: bool = False, event_filter_type: WorkflowHistoryEventFilterType = WorkflowHistoryEventFilterType.ALL_EVENT, skip_archival: bool = False, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = None) -> WorkflowHistoryEventAsyncIterator: (source) ¶

Undocumented

async def _start_update(self, update: Union[str, Callable], arg: Any = temporalio.common._arg_unset, *, wait_for_stage: WorkflowUpdateStage, args: Sequence[Any] = [], id: Optional[str] = None, result_type: Optional[Type] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = 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