class documentation

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 for cancel and terminate calls if present to ensure the cancel and terminate happen for 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 Run ID used for signal, query, and update calls if present to ensure the signal/query/update happen on 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
RPCErrorWorkflow 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
WorkflowExecutionDescriptionWorkflow details.
Raises
RPCErrorWorkflow 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

Warning

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

Parameters
update:Union[str, Callable]Update function or name on the workflow.
arg:AnySingle 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
AnyUndocumented
Raises
WorkflowUpdateFailedErrorIf the update failed.
WorkflowUpdateRPCTimeoutOrCancelledErrorThis update call timed out or was cancelled. This doesn't mean the update itself was timed out or cancelled.
RPCErrorThere 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:boolWhether the event fetching request will wait for new events or just return right away.
event_filter_type:WorkflowHistoryEventFilterTypeWhich events to obtain.
skip_archival:boolWhether 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
WorkflowHistoryEventAsyncIteratorAn 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:strUpdate 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:strUpdate 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_typeThe result type to deserialize into if known.
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:AnySingle 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
AnyResult of the query.
Raises
WorkflowQueryRejectedErrorA query reject condition was satisfied.
RPCErrorWorkflow 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)

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:boolIf 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
ReturnTypeResult of the workflow after being converted by the data converter.
Raises
WorkflowFailureErrorWorkflow failed, was cancelled, was terminated, or timed out. Use the WorkflowFailureError.cause to see the underlying reason.
ExceptionOther 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:AnySingle 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
RPCErrorWorkflow 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

Warning

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

Parameters
update:Union[str, Callable]Update function or name on the workflow.
arg:AnySingle argument to the update.
wait_for_stage:WorkflowUpdateStageRequired stage to wait until returning. 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
WorkflowUpdateRPCTimeoutOrCancelledErrorThis update call timed out or was cancelled. This doesn't mean the update itself was timed out or cancelled.
RPCErrorThere 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:AnyDetails 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
RPCErrorWorkflow could not be terminated.
@property
first_execution_run_id: Optional[str] = (source)

Run ID used for cancel and terminate calls if present to ensure the cancel and terminate happen for 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.

ID for the workflow.

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.

Run ID used for signal, query, and update calls if present to ensure the signal/query/update happen on 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

Undocumented

_first_execution_run_id = (source)

Undocumented

Undocumented

_result_run_id = (source)

Undocumented

_result_type = (source)

Undocumented

Undocumented