temporalio.client.Client

class documentation

class Client: (source)

Constructors: Client.connect(target_host, namespace, api_key, data_converter, interceptors, ...), Client(service_client, namespace, data_converter, interceptors, default_workflow_query_reject_condition)

View In Hierarchy

Client for accessing Temporal.

Most users will use connect to create a client. The service property provides access to a raw gRPC client. To create another client, like for a different namespace, Client may be directly instantiated with a service of another.

Clients are not thread-safe and should only be used in the event loop they are first connected in. If a client needs to be used from another thread than where it was created, make sure the event loop where it was created is captured, and then call asyncio.run_coroutine_threadsafe with the client call and that event loop.

Clients do not work across forks since runtimes do not work across forks.

Async Static Method	`connect`	Connect to a Temporal server.
Method	`__init__`	Create a Temporal client from a service client.
Method	`api_key.setter`	Update the API key for this client.
Method	`config`	Config, as a dictionary, used to create this client.
Async Method	`count_workflows`	Count workflows.
Async Method	`create_schedule`	Create a schedule and return its handle.
Async Method	`execute_update_with_start_workflow`	Send an update-with-start request and wait for the update to complete.
Async Method	`execute_workflow`	Start a workflow and wait for completion.
Method	`get_async_activity_handle`	Get an async activity handle.
Method	`get_schedule_handle`	Get a schedule handle for the given ID.
Async Method	`get_worker_build_id_compatibility`	Get the Build ID compatibility sets for a specific task queue.
Async Method	`get_worker_task_reachability`	Determine if some Build IDs for certain Task Queues could have tasks dispatched to them.
Method	`get_workflow_handle`	Get a workflow handle to an existing workflow by its ID.
Method	`get_workflow_handle_for`	Get a typed workflow handle to an existing workflow by its ID.
Async Method	`list_schedules`	List schedules.
Method	`list_workflows`	List workflows.
Method	`rpc_metadata.setter`	Update the headers for this client.
Async Method	`start_update_with_start_workflow`	Send an update-with-start request and wait for it to be accepted.
Async Method	`start_workflow`	Start a workflow and return its handle.
Async Method	`update_worker_build_id_compatibility`	Used to add new Build IDs or otherwise update the relative compatibility of Build Ids as defined on a specific task queue for the Worker Versioning feature.
Property	`api_key`	API key for every call made by this client.
Property	`data_converter`	Data converter used by this client.
Property	`identity`	Identity used in calls by this client.
Property	`namespace`	Namespace used in calls by this client.
Property	`operator_service`	Raw gRPC operator service client.
Property	`rpc_metadata`	Headers for every call made by this client.
Property	`service_client`	Raw gRPC service client.
Property	`test_service`	Raw gRPC test service client.
Property	`workflow_service`	Raw gRPC workflow service client.
Async Method	`_start_update_with_start`	Undocumented
Instance Variable	`_config`	Undocumented
Instance Variable	`_impl`	Undocumented

@staticmethod
async def connect(target_host: str, *, namespace: str = 'default', api_key: Optional[str] = None, data_converter: temporalio.converter.DataConverter = temporalio.converter.DataConverter.default, interceptors: Sequence[Interceptor] = [], default_workflow_query_reject_condition: Optional[temporalio.common.QueryRejectCondition] = None, tls: Union[bool, TLSConfig] = False, retry_config: Optional[RetryConfig] = None, keep_alive_config: Optional[KeepAliveConfig] = KeepAliveConfig.default, rpc_metadata: Mapping[str, str] = {}, identity: Optional[str] = None, lazy: bool = False, runtime: Optional[temporalio.runtime.Runtime] = None, http_connect_proxy_config: Optional[HttpConnectProxyConfig] = None) -> Client: (source) ¶

Connect to a Temporal server.

Parameters
target_host:`str`	`host:port` for the Temporal server. For local development, this is often "localhost:7233".
namespace:`str`	Namespace to use for client calls.
api_key:`Optional[str]`	API key for Temporal. This becomes the "Authorization" HTTP header with "Bearer " prepended. This is only set if RPC metadata doesn't already have an "authorization" key.
data_converter:`temporalio.converter.DataConverter`	Data converter to use for all data conversions to/from payloads.
interceptors:`Sequence[Interceptor]`	Set of interceptors that are chained together to allow intercepting of client calls. The earlier interceptors wrap the later ones. Any interceptors that also implement `temporalio.worker.Interceptor` will be used as worker interceptors too so they should not be given when creating a worker.
default_workflow_query_reject_condition:`Optional[temporalio.common.QueryRejectCondition]`	The default rejection condition for workflow queries if not set during query. See `WorkflowHandle.query` for details on the rejection condition.
tls:`Union[bool, TLSConfig]`	If false, the default, do not use TLS. If true, use system default TLS configuration. If TLS configuration present, that TLS configuration will be used.
retry_config:`Optional[RetryConfig]`	Retry configuration for direct service calls (when opted in) or all high-level calls made by this client (which all opt-in to retries by default). If unset, a default retry configuration is used.
keep_alive_config:`Optional[KeepAliveConfig]`	Keep-alive configuration for the client connection. Default is to check every 30s and kill the connection if a response doesn't come back in 15s. Can be set to `None` to disable.
rpc_metadata:`Mapping[str, str]`	Headers to use for all calls to the server. Keys here can be overriden by per-call RPC metadata keys.
identity:`Optional[str]`	Identity for this client. If unset, a default is created based on the version of the SDK.
lazy:`bool`	If true, the client will not connect until the first call is attempted or a worker is created with it. Lazy clients cannot be used for workers.
runtime:`Optional[temporalio.runtime.Runtime]`	The runtime for this client, or the default if unset.
http_connect_proxy_config:`Optional[HttpConnectProxyConfig]`	Configuration for HTTP CONNECT proxy.
Returns
`Client`	Undocumented

def __init__(self, service_client: temporalio.service.ServiceClient, *, namespace: str = 'default', data_converter: temporalio.converter.DataConverter = temporalio.converter.DataConverter.default, interceptors: Sequence[Interceptor] = [], default_workflow_query_reject_condition: Optional[temporalio.common.QueryRejectCondition] = None): (source) ¶

Create a Temporal client from a service client.

See connect for details on the parameters.

@api_key.setter
def api_key(self, value: Optional[str]): (source) ¶

Update the API key for this client.

This is only set if RPCmetadata doesn't already have an "authorization" key.

def config(self) -> ClientConfig: (source) ¶

Config, as a dictionary, used to create this client.

This makes a shallow copy of the config each call.

async def count_workflows(self, query: Optional[str] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = None) -> WorkflowExecutionCount: (source) ¶

Count workflows.

Parameters
query:`Optional[str]`	A Temporal visibility filter. See Temporal documentation concerning visibility list filters.
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
`WorkflowExecutionCount`	Count of workflows.

async def create_schedule(self, id: str, schedule: Schedule, *, trigger_immediately: bool = False, backfill: Sequence[ScheduleBackfill] = [], memo: Optional[Mapping[str, Any]] = None, search_attributes: Optional[Union[temporalio.common.TypedSearchAttributes, temporalio.common.SearchAttributes]] = None, static_summary: Optional[str] = None, static_details: Optional[str] = None, rpc_metadata: Mapping[str, str] = {}, rpc_timeout: Optional[timedelta] = None) -> ScheduleHandle: (source) ¶

Create a schedule and return its handle.

Parameters
id:`str`	Unique identifier of the schedule.
schedule:`Schedule`	Schedule to create.
trigger_immediately:`bool`	If true, trigger one action immediately when creating the schedule.
backfill:`Sequence[ScheduleBackfill]`	Set of time periods to take actions on as if that time passed right now.
memo:`Optional[Mapping[str, Any]]`	Memo for the schedule. Memo for a scheduled workflow is part of the schedule action.
search_attributes:`Optional[Union[temporalio.common.TypedSearchAttributes, temporalio.common.SearchAttributes]]`	Search attributes for the schedule. Search attributes for a scheduled workflow are part of the scheduled action. The dictionary form of this is DEPRECATED, use `temporalio.common.TypedSearchAttributes`.
static_summary:`Optional[str]`	A single-line fixed summary for this workflow execution that may appear in the UI/CLI. This can be in single-line Temporal markdown format.
static_details:`Optional[str]`	General fixed details for this workflow execution that may appear in UI/CLI. This can be in Temporal markdown format and can span multiple lines. This is a fixed value on the workflow that cannot be updated. For details that can be updated, use `temporalio.workflow.get_current_details` within the workflow.
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
`ScheduleHandle`	A handle to the created schedule.
Raises
`ScheduleAlreadyRunningError`	If a schedule with this ID is already running.

Parameters
update:`Union[str, Callable]`	Update function or name on the workflow. arg: Single argument to the update.
arg:`Any`	Undocumented
start_workflow_operation:`WithStartWorkflowOperation[Any, Any]`	a WithStartWorkflowOperation definining the WorkflowIDConflictPolicy and how to start the workflow in the event that a workflow is started.
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 starting the workflow or sending the update to the workflow.

Parameters
workflow_id:`Optional[str]`	Workflow ID for the activity. Cannot be set if task_token is set.
run_id:`Optional[str]`	Run ID for the activity. Cannot be set if task_token is set.
activity_id:`Optional[str]`	ID for the activity. Cannot be set if task_token is set.
task_token:`Optional[bytes]`	Task token for the activity. Cannot be set if any of the id parameters are set.
Returns
`AsyncActivityHandle`	A handle that can be used for completion or heartbeat.

Parameters
task_queue:`str`	The task queue to target.
max_sets:`Optional[int]`	The maximum number of sets to return. If not specified, all sets will be returned.
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
`WorkerBuildIdVersionSets`	Undocumented

Parameters
build_ids:`Sequence[str]`	The Build IDs to query the reachability of. At least one must be specified.
task_queues:`Sequence[str]`	Task Queues to restrict the query to. If not specified, all Task Queues will be searched. When requesting a large number of task queues or all task queues associated with the given Build IDs in a namespace, all Task Queues will be listed in the response but some of them may not contain reachability information due to a server enforced limit. When reaching the limit, task queues that reachability information could not be retrieved for will be marked with a `NotFetched` entry in {@link BuildIdReachability.taskQueueReachability}. The caller may issue another call to get the reachability for those task queues.
reachability_type:`Optional[TaskReachabilityType]`	The kind of reachability this request is concerned with.
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
`WorkerTaskReachability`	Undocumented

Parameters
workflow_id:`str`	Workflow ID to get a handle to.
run_id:`Optional[str]`	Run ID that will be used for all calls.
first_execution_run_id:`Optional[str]`	First execution run ID used for cancellation and termination.
result_type:`Optional[Type]`	The result type to deserialize into if known.
Returns
`WorkflowHandle[Any, Any]`	The workflow handle.

Parameters
workflow:`Union[MethodAsyncNoParam[SelfType, ReturnType], MethodAsyncSingleParam[SelfType, Any, ReturnType]]`	The workflow run method to use for typing the handle.
workflow_id:`str`	Workflow ID to get a handle to.
run_id:`Optional[str]`	Run ID that will be used for all calls.
first_execution_run_id:`Optional[str]`	First execution run ID used for cancellation and termination.
Returns
`WorkflowHandle[SelfType, ReturnType]`	The workflow handle.

Parameters
query:`Optional[str]`	A Temporal visibility list filter. See Temporal documentation concerning visibility list filters including behavior when left unset.
page_size:`int`	Maximum number of results for each page.
next_page_token:`Optional[bytes]`	A previously obtained next page token if doing pagination. Usually not needed as the iterator automatically starts from the beginning.
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
`ScheduleAsyncIterator`	An async iterator that can be used with `async for`.

Parameters
workflow:`Union[str, Callable[..., Awaitable[Any]]]`	String name or class method decorated with `@workflow.run` for the workflow to start.
arg:`Any`	Single argument to the workflow.
args:`Sequence[Any]`	Multiple arguments to the workflow. Cannot be set if arg is.
id:`str`	Unique identifier for the workflow execution.
task_queue:`str`	Task queue to run the workflow on.
result_type:`Optional[Type]`	For string workflows, this can set the specific result type hint to deserialize into.
execution_timeout:`Optional[timedelta]`	Total workflow execution timeout including retries and continue as new.
run_timeout:`Optional[timedelta]`	Timeout of a single workflow run.
task_timeout:`Optional[timedelta]`	Timeout of a single workflow task.
id_reuse_policy:`temporalio.common.WorkflowIDReusePolicy`	How already-existing IDs are treated.
id_conflict_policy:`temporalio.common.WorkflowIDConflictPolicy`	How already-running workflows of the same ID are treated. Default is unspecified which effectively means fail the start attempt. This cannot be set if `id_reuse_policy` is set to terminate if running.
retry_policy:`Optional[temporalio.common.RetryPolicy]`	Retry policy for the workflow.
cron_schedule:`str`	See https://docs.temporal.io/docs/content/what-is-a-temporal-cron-job/
memo:`Optional[Mapping[str, Any]]`	Memo for the workflow.
search_attributes:`Optional[Union[temporalio.common.TypedSearchAttributes, temporalio.common.SearchAttributes]]`	Search attributes for the workflow. The dictionary form of this is deprecated, use `temporalio.common.TypedSearchAttributes`.
static_summary:`Optional[str]`	A single-line fixed summary for this workflow execution that may appear in the UI/CLI. This can be in single-line Temporal markdown format.
static_details:`Optional[str]`	General fixed details for this workflow execution that may appear in UI/CLI. This can be in Temporal markdown format and can span multiple lines. This is a fixed value on the workflow that cannot be updated. For details that can be updated, use `temporalio.workflow.get_current_details` within the workflow.
start_delay:`Optional[timedelta]`	Amount of time to wait before starting the workflow. This does not work with `cron_schedule`.
start_signal:`Optional[str]`	If present, this signal is sent as signal-with-start instead of traditional workflow start.
start_signal_args:`Sequence[Any]`	Arguments for start_signal if start_signal present.
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.
request_eager_start:`bool`	Potentially reduce the latency to start this workflow by encouraging the server to start it on a local worker running with this same client. This is currently experimental.
stack_level:`int`	Undocumented
Returns
`WorkflowHandle[Any, Any]`	A workflow handle to the started workflow.
Raises
`temporalio.exceptions.WorkflowAlreadyStartedError`	Workflow has already been started.
`RPCError`	Workflow could not be started for some other reason.