temporalio.client.ActivityHandle

class documentation

class ActivityHandle(Generic[ReturnType]): (source)

Constructor: ActivityHandle(client, id, run_id, result_type)

Handle representing an activity execution not started by a workflow.

Warning

This API is experimental.

Method	`__init__`	Create activity handle.
Async Method	`cancel`	Request cancellation of the activity.
Async Method	`describe`	Describe the activity execution.
Async Method	`result`	Wait for result of the activity.
Async Method	`terminate`	Terminate the activity execution immediately.
Property	`id`	ID of the activity.
Property	`run_id`	Run ID of the activity.
Async Method	`_poll_until_outcome`	Poll for activity result until it's available.
Instance Variable	`_client`	Undocumented
Instance Variable	`_id`	Undocumented
Instance Variable	`_known_outcome`	Undocumented
Instance Variable	`_result_type`	Undocumented
Instance Variable	`_run_id`	Undocumented
Property	`_data_converter`	Undocumented

def __init__(self, client: Client, id: str, *, run_id: str | None = None, result_type: type | None = None): (source) ¶

Create activity handle.

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

Request cancellation of the activity.

Warning

This API is experimental.

Requesting cancellation of an activity does not automatically transition the activity to canceled status. If the activity is heartbeating, a exceptions.CancelledError exception will be raised when receiving the heartbeat response; if the activity allows this exception to bubble out, the activity will transition to canceled status. If the activity it is not heartbeating, this method will have no effect on activity status.

Parameters
reason:`str \| None`	Reason for the cancellation. Recorded and available via describe.
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for the RPC call.

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

Describe the activity execution.

Warning

This API is experimental.

Parameters
long_poll_token:`bytes \| None`	Token from a previous describe response. If provided, the request will long-poll until the activity state changes.
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for the RPC call.

Returns
`ActivityExecutionDescription`	Activity execution description.

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

Wait for result of the activity.

Warning

This API is experimental.

The result may already be known if this method has been called before, in which case no network call is made. Otherwise the result will be polled for until it is available.

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 each RPC call. Note: this is the timeout for each RPC call while polling, not a timeout for the function as a whole. If an individual RPC times out, it will be retried until the result is available.

Returns
`ReturnType`	The result of the activity.

Raises
`ActivityFailureError`	If the activity completed with a failure.
`RPCError`	Activity result could not be fetched for some reason.

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

Terminate the activity execution immediately.

Warning

This API is experimental.

Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a running attempt and will be requested to be canceled by the server when it heartbeats.

Parameters
reason:`str \| None`	Reason for the termination.
rpc_metadata:`Mapping[str, str \| bytes]`	Headers used on the RPC call.
rpc_timeout:`timedelta \| None`	Optional RPC deadline to set for the RPC call.