Globus Compute Client¶

The Compute SDK Client wraps the Compute web services API. While the Client is the main interface to the web services, most users will want the higher-level Globus Compute Executor.

For usage examples and explanations, please see the Client User Guide.

class globus_compute_sdk.Client(environment: str | None = None, local_compute_services: bool = False, do_version_check: bool = True, *, code_serialization_strategy: SerializationStrategy | None = None, data_serialization_strategy: SerializationStrategy | None = None, app: GlobusApp | None = None, authorizer: GlobusAuthorizer | None = None, **kwargs)¶

Main class for interacting with the Globus Compute service

Holds helper operations for performing common tasks with the Globus Compute service.

Initialize the client

Parameters:

environment (str) – For internal use only. The name of the environment to use.
local_compute_services (str) – For internal use only. TODO
do_version_check (bool) – Set to False to skip the version compatibility check on client initialization Default: True
code_serialization_strategy (SerializationStrategy) – Strategy to use when serializing function code. If None, globus_compute_sdk.serialize.DEFAULT_STRATEGY_CODE will be used.
data_serialization_strategy (SerializationStrategy) – Strategy to use when serializing function arguments. If None, globus_compute_sdk.serialize.DEFAULT_STRATEGY_DATA will be used.
app (GlobusApp) – A GlobusApp that will handle authorization and storing and validating tokens. If None, a standard GlobusApp will be used. Mutually exclusive with authorizer.
authorizer (GlobusAuthorizer) – A GlobusAuthorizer that will generate authorization headers. Mutually exclusive with app.

version_check(endpoint_version: str | None = None) → None¶

Check this client version meets the service’s minimum supported version.

Raises a VersionMismatch error on failure.

logout()¶: Remove credentials from your local system

get_task(task_id)¶

Get a Globus Compute task.

Parameters:: task_id (str) – UUID of the task
Returns:: Task block containing “status” key.
Return type:: dict

get_result(task_id: UUID | str)¶

Get the result of a Globus Compute task

This method is a convenience intended for simple REPL interactions. In general, strongly prefer get_batch_result() to collect task information in bulk, rather than a loop around this method.

Parameters:: task_id – a task identifier, as returned a submission to the web-service
Returns:: a dictionary containing the task status and result information
Raises:: If task failed, the task exception (reconstituted from remote source)

get_batch_result(task_id_list: list[UUID | str]) → dict[str, dict]¶

Request status of list of tasks

The returned dictionary maps task identifiers to the task state. An example interaction:

# Task identifiers are UUIDs, as returned by the API for tasks previously
# submitted.
>>> previously_submitted_task_identifiers = [
...   "00000000-0000-0000-0000-000000000000",
...   "00000000-0000-0000-0000-000000000001"
... ]
>>> c = Client()
>>> c.get_batch_result(previously_submitted_task_identifiers)
{
    '00000000-0000-0000-0000-000000000000': {
        'pending': True,
        'status': 'unknown'
    },
    '00000000-0000-0000-0000-000000000001': {
        'pending': False,
        'status': 'success',
        'result': None,
        'completion_t': '1234567890.9876543'
    },
}

The pending field states whether the task has completed. In this example, 0...0 is not yet finished, while 0...1 has a status of success, a result of None, and completed at unixtime of 1234567890.

Note that the order in the returned dictionary is not guaranteed.

Parameters:: task_id_list – a list of strings – task identifiers for previously-submitted tasks

run(*args, endpoint_id: UUID | str, function_id: UUID | str, **kwargs) → str¶

Initiate an invocation

Parameters:

*args (Any) – Args as specified by the function signature
endpoint_id (uuid str) – Endpoint UUID string. Required
function_id (uuid str) – Function UUID string. Required

Returns:

task_id (str)
UUID string that identifies the task

create_batch(task_group_id: UUID | str | None = None, resource_specification: dict[str, Any] | None = None, user_endpoint_config: dict[str, Any] | None = None, create_websocket_queue: bool = False, result_serializers: list[str] | None = None) → Batch¶

Create a Batch instance to handle batch submission in Globus Compute

Parameters:

endpoint_id (UUID-like) – ID of the endpoint where the tasks in this batch will be executed
task_group_id (UUID-like (optional)) – Associate this batch with a pre-existing Task Group. If there is no Task Group associated with the given ID, or the user is not authorized to use it, the services will respond with an error. If task_group_id is not specified, the services will create a Task Group.
resource_specification (dict (optional)) – Specify resource requirements for individual task execution.
user_endpoint_config (dict (optional)) – User endpoint configuration values as described and allowed by endpoint administrators
create_websocket_queue (bool) – Whether to create a websocket queue for the task_group_id if it isn’t already created
result_serializers (list[str] (optional)) – A list of import paths to Compute serialization strategies, which the endpoint will iterate through when serializing task results.

Return type:

Batch instance

batch_run(endpoint_id: UUID | str, batch: Batch) → dict[str, str | dict[str, list[str]]]¶

Initiate a batch of tasks to Globus Compute

Parameters:

endpoint_id – The endpoint identifier to which to send the batch
batch – a Batch object

Returns:

a dictionary with the following keys:

tasks: a mapping of function IDs to lists of task IDs
request_id: arbitrary unique string the web-service assigns this request (only intended for help with support requests)
task_group_id: the task group identifier associated with the submitted tasks
endpoint_id: the endpoint the tasks were submitted to

Parameters:

name (str) – Name of the endpoint
endpoint_id (str | UUID | None) – The uuid of the endpoint
metadata (dict | None) – Endpoint metadata
multi_user (bool | None) – Whether the endpoint supports multiple users
high_assurance (bool | None) – Whether the endpoint should be high assurance capable
display_name (str | None) – The display name of the endpoint
allowed_functions (list[str | UUID] | None) – List of functions that are allowed to be run on the endpoint
auth_policy (str | UUID | None) – Endpoint users are evaluated against this Globus authentication policy
subscription_id (str | UUID | None) – Subscription ID to associate endpoint with
public (bool | None) – Indicates if all users can discover the multi-user endpoint.
admins (list[UUID_LIKE_T] | tuple[UUID_LIKE_T, ...] | None) – A list of Globus Auth identity IDs that have administrative access to the endpoint, in addition to the owner. This field requires an active Globus subscription (i.e., subscription_id).

Returns:

{‘endpoint_id’<>,: ’address’ : <>, ‘client_ports’: <>}

Return type:

dict

get_endpoint_status(endpoint_uuid)¶

Get the status reports for an endpoint.

Parameters:: endpoint_uuid (str) – UUID of the endpoint in question
Returns:: The details of the endpoint’s stats
Return type:: dict

get_endpoint_metadata(endpoint_uuid)¶

Get the metadata for an endpoint.

Parameters:: endpoint_uuid (str) – UUID of the endpoint in question
Returns:: Informational fields about the metadata, such as IP, hostname, and configuration values. If there were any issues deserializing this data, may also include an “errors” key.
Return type:: dict

get_endpoints(role: str | None = None)¶

Get a list of endpoints available to the current user.

Parameters:: role (str) – Filter returned list by user’s association to endpoints (e.g., owner, any). The default value is unset, in which case the API (currently) assumes owner.
Returns:: A list of dictionaries which contain endpoint information
Return type:: list

register_function(function, description=None, metadata: dict | None = None, public=False, group=None, ha_endpoint_id: UUID | str | None = None) → str¶

Parameters:

function (Python Function) – The function to be registered for remote execution
description (str) – Description of the function. If this is None, and the function has a docstring, that docstring is uploaded as the function’s description instead; otherwise, if this has a value, it’s uploaded as the description, even if the function has a docstring.
metadata (dict) – Function metadata (E.g., Python version used when serializing the function)
public (bool) – Whether or not the function is publicly accessible. Default = False
group (str) – A globus group uuid to share this function with
ha_endpoint_id (UUID | str | None) – Users will only be able to run this function on the specified HA endpoint. Since HA functions cannot be shared, this argument is mutually exclusive with the group and public arguments.

Returns:

function uuid – UUID identifier for the registered function

Return type:

str

The standard .register_function() method expects a callable function object, which it then serializes using the specified code serialization strategy. In contrast, this method enables the user to directly provide an arbitrary source code string and entrypoint function name.

Important

This method will ignore the current code serialization strategy and use PureSourceTextInspect instead.

Parameters:

source – The source code string
function_name – The name of the entrypoint function within the source code
description – Description of the function source code
metadata – Function source code metadata (e.g., Python version)
public – Whether the function source code is publicly accessible
group – A globus group UUID to share this function source code with
ha_endpoint_id – Users will only be able to run this function source code on the specified HA endpoint. Since HA functions cannot be shared, this argument is mutually exclusive with the group and public arguments.

Returns:

UUID string of the registered function

Return type:

str

get_function(function_id: UUID | str)¶

Submit a request for details about a registered function.

Parameters:: function_id (UUID | str) – UUID of the registered function
Returns:: Information about the registered function, such as name, description, serialized source code, python version, etc.
Return type:: dict

get_allowed_functions(endpoint_id: UUID | str)¶

List the functions that are allowed to execute on this endpoint :param endpoint_id: The ID of the endpoint :type endpoint_id: UUID | str

Returns:: The response of the request
Return type:: json

stop_endpoint(endpoint_id: str)¶

Stop an endpoint by dropping it’s active connections.

Parameters:: endpoint_id (str) – The uuid of the endpoint
Returns:: The response of the request
Return type:: json

delete_endpoint(endpoint_id: str)¶

Delete an endpoint

Parameters:: endpoint_id (str) – The uuid of the endpoint
Returns:: The response of the request
Return type:: json

delete_function(function_id: str)¶

Delete a function

Parameters:: function_id (str) – The UUID of the function
Returns:: The response of the request
Return type:: json

get_worker_hardware_details(endpoint_id: UUID | str) → str¶

Run a function to get hardware details. Returns a task ID; when that task is finished, the result of the run will be a string containing hardware information on the nodes that the endpoint workers are running on. For example:

from globus_compute_sdk import Client
gcc = Client()
task_id = gcc.get_worker_hardware_details(ep_uuid)
# wait some time...
print(gcc.get_result(task_id))

class globus_compute_sdk.sdk.batch.Batch(task_group_id: UUID | str | None, resource_specification: dict[str, Any] | None = None, user_endpoint_config: dict[str, Any] | None = None, request_queue=False, serializer: ComputeSerializer | None = None, user_runtime: UserRuntime | None = None, result_serializers: list[str] | None = None)¶

Utility class for creating batch submission in Globus Compute

Parameters:

task_group_id – UUID of task group to which to submit the batch
resource_specification – Specify resource requirements for individual task execution
user_endpoint_config – User endpoint configuration values as described and allowed by endpoint administrators
request_queue – Whether to request a result queue from the web service; typically only used by the Executor
serializer – Used to serialize task args and kwargs
user_runtime – Information about the runtime used to create and prepare this batch, such as Python and Globus Compute SDK versions
result_serializers – A list of serialization strategy import paths to pass to the endpoint for use in serializing execution results.

add(function_id: UUID | str, args: tuple[Any, ...] | None = None, kwargs: dict[str, Any] | None = None) → None¶

Add a function invocation to a batch submission

Parameters:

function_id – UUID of registered function. (Required)
args – arguments as required by the function signature
kwargs – Keyword arguments as required by the function signature

prepare() → dict[str, str | list[tuple[str, str, str]]]¶

Prepare the payload to be POSTed to web service in a batch

Returns:: a dictionary suitable for JSONification for POSTing to the web service

class globus_compute_sdk.sdk.batch.UserRuntime(globus_compute_sdk_version: str, globus_sdk_version: str, python_version: str, python: PythonInfo, platform: PlatformInfo)¶

Information about a user’s runtime environment, which is sent along with task submissions to the MEP user config renderer.

Parameters:

globus_compute_sdk_version (str) – Version string of the Globus Compute SDK (e.g., "3.14.0")
globus_sdk_version (str) – Version string of the Globus SDK dependency (e.g., "3.63.0")
python_version (str) – Complete Python version string from sys.version (Deprecated; use python instead)
python (PythonInfo) – Information about the Python runtime
platform (PlatformInfo) – General platform information from the host

class PythonInfo(version: str, version_description: str, version_tuple: tuple[int, int, int], version_info: tuple[int, int, int, str, int], implementation: str, compiler: str)¶

Information about the Python runtime

Parameters:

version (str) – Python version string (e.g., "3.13.7")
version_description (str) – Complete Python version string from sys.version (e.g., "3.13.7 (main, Sep 30 2025, 03:50:19) [GCC 14.2.0]")
version_tuple (tuple[int, int, int]) – Python version as a tuple (e.g., (3, 13, 7))
version_info (tuple[int, int, int, str, int]) – Python version info from tuple(sys.version_info) (e.g., (3, 13, 7, "final", 0))
implementation (str) – Python implementation (e.g., "CPython")
compiler (str) – String identifying the compiler used for compiling Python (e.g., "Clang 14.0.6")

class PlatformInfo(architecture: tuple[str, str], machine: str, node: str, platform: str, processor: str, release: str)¶

General platform information from the host

Parameters:

architecture (tuple[str, str]) – Host architecture tuple (e.g., ("64bit", "ELF"))
machine (str) – Host machine type (e.g., "x86_64")
node (str) – Host node name (e.g., "login03")
platform (str) – Host platform (e.g., "Linux-6.14.0-29-generic-x86_64-with-glibc2.39")
processor (str) – Host processor name (e.g., "x86_64")
release (str) – Host OS release (e.g., "6.16.5-2-generic")