temporalio.client.WorkflowHandle

class documentation

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

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	`query`	Query the workflow.
Async Method	`result`	Wait for result of the workflow.
Async Method	`signal`	Send a signal to the workflow.
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` and `query` calls if present to ensure the query or signal happen on this exact run.
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 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] = [], 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.
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)

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.

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 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.

@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)

Run ID used for signal and query calls if present to ensure the query or signal 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.

_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