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	`pause`	Pause the activity.
Async Method	`restore_original_options`	Restore the activity's options to the ones it was created with.
Async Method	`result`	Wait for result of the activity.
Async Method	`terminate`	Terminate the activity execution immediately.
Async Method	`unpause`	Unpause the activity, allowing it to be scheduled or retried again.
Async Method	`update_options`	Update the activity's options.
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, *, include_input: bool = False, include_outcome: bool = False, include_heartbeat_details: bool = False, include_last_failure: bool = False, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> ActivityExecutionDescription: (source) ¶

Describe the activity execution.

Warning

This API is experimental.

Parameters
include_input:`bool`	Include activity input in the response if available.
include_outcome:`bool`	Include activity outcome in the response if available.
include_heartbeat_details:`bool`	Include heartbeat details in the response if available.
include_last_failure:`bool`	Include last failure in the response if available.
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 pause(self, *, reason: str | None = None, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None): (source) ¶

Pause the activity.

A paused activity is not scheduled or retried until it is unpaused via unpause.

Warning

This API is experimental.

Parameters
reason:`str \| None`	Reason for pausing. 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 restore_original_options(self, *, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> ActivityExecutionOptions: (source) ¶

Restore the activity's options to the ones it was created with.

This is a separate call rather than an option on update_options because the server rejects a request that combines the restore flag with any other option.

Warning

This API is experimental.

Parameters
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
`ActivityExecutionOptions`	The activity options as resolved by the server after the restore.

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.

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

Unpause the activity, allowing it to be scheduled or retried again.

Warning

This API is experimental.

Parameters
reason:`str \| None`	Reason for unpausing. Recorded on the server.
jitter:`timedelta \| None`	If set, the activity starts at a random time within this duration rather than immediately.
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 update_options(self, updates: Sequence[ActivityOptionsUpdate[Any]], *, rpc_metadata: Mapping[str, str | bytes] = {}, rpc_timeout: timedelta | None = None) -> ActivityExecutionOptions: (source) ¶

Update the activity's options.

Only the options named by updates are changed; anything not named is left as-is. An update created with ActivityOptionsKey.value_unset clears that option.

Each option may be named at most once; naming the same option twice raises ValueError.

Warning

This API is experimental.

Parameters
updates:`Sequence[ActivityOptionsUpdate[Any]]`	Options to change, built from `ActivityOptionsKeys`.
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
`ActivityExecutionOptions`	The activity options as resolved by the server after the update.

Raises
`ValueError`	If `updates` is empty or names the same option twice.

@property

id: str = (source) ¶

ID of the activity.

@property

run_id: str | None = (source) ¶

Run ID of the activity.

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

Poll for activity result until it's available.

_client = (source) ¶

Undocumented

_id = (source) ¶

Undocumented

_known_outcome: temporalio.api.activity.v1.ActivityExecutionOutcome | None = (source) ¶

Undocumented

_result_type = (source) ¶

Undocumented

_run_id = (source) ¶

Undocumented

@functools.cached_property

_data_converter: temporalio.converter.DataConverter = (source) ¶

Undocumented