The FuncX Client

class funcx.FuncXClient(http_timeout=None, funcx_home='~/.funcx', asynchronous: Optional[bool] = None, loop=None, environment: Optional[str] = None, funcx_service_address: Optional[str] = None, results_ws_uri: Optional[str] = None, warn_about_url_mismatch: Optional[bool] = None, task_group_id: Union[None, uuid.UUID, str] = None, do_version_check: bool = True, openid_authorizer: Optional[Any] = None, search_authorizer: Optional[Any] = None, fx_authorizer: Optional[Any] = None, *, login_manager: Optional[funcx.sdk.login_manager.protocol.LoginManagerProtocol] = None, **kwargs)

Main class for interacting with the funcX service

Holds helper operations for performing common tasks with the funcX service.

Initialize the client

Parameters:
  • http_timeout (int) – Timeout for any call to service in seconds. Default is no timeout

  • environment (str) – For internal use only. The name of the environment to use. Sets funcx_service_address and results_ws_uri unless they are already passed in.

  • funcx_service_address (str) – For internal use only. The address of the web service.

  • results_ws_uri (str) –

    For internal use only. The address of the websocket service.

    DEPRECATED - use FuncXExecutor instead.

  • warn_about_url_mismatch (bool) –

    For internal use only. If true, a warning is logged if funcx_service_address and results_ws_uri appear to point to different environments.

    DEPRECATED - use FuncXExecutor instead.

  • do_version_check (bool) – Set to False to skip the version compatibility check on client initialization Default: True

  • asynchronous (bool) –

    Should the API use asynchronous interactions with the web service? Currently only impacts the run method.

    DEPRECATED - this was an early attempt at asynchronous result gathering.

    Use the FuncXExecutor instead.

    Default: False

  • loop (AbstractEventLoop) –

    If asynchronous mode is requested, then you can provide an optional event loop instance. If None, then we will access asyncio.get_event_loop()

    DEPRECATED - part of an early attempt at asynchronous result gathering.

    Use the FuncXExecutor instead.

    Default: None

  • task_group_id (str|uuid.UUID) – Set the TaskGroup ID (a UUID) for this FuncXClient instance. Typically, one uses this to submit new tasks to an existing session or to reestablish FuncXExecutor futures. Default: None (will be auto generated)

  • BaseClient. (Keyword arguments are the same as for) –

version_check(endpoint_version: Optional[str] = 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 funcX task.

Parameters:

task_id (str) – UUID of the task

Returns:

Task block containing “status” key.

Return type:

dict

get_result(task_id)

Get the result of a funcX task

Parameters:

task_id (str) – UUID of the task

Returns:

Result obj

Return type:

If task completed

Raises:

Exception obj – Exception due to which the task failed:

get_batch_result(task_id_list)

Request status for a batch of task_ids

run(*args, endpoint_id=None, function_id=None, **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

  • asynchronous (bool) – Whether or not to run the function asynchronously

Returns:

  • task_id (str)

  • UUID string that identifies the task if asynchronous is False

  • funcX Task (asyncio.Task)

  • A future that will eventually resolve into the function’s result if

  • asynchronous is True

create_batch(task_group_id=None, create_websocket_queue=False) funcx.sdk.batch.Batch

Create a Batch instance to handle batch submission in funcX

Parameters:
  • task_group_id (str) – Override the session wide session_task_group_id with a different task_group_id for this batch. If task_group_id is not specified, it will default to using the client’s session_task_group_id

  • create_websocket_queue (bool) – Whether to create a websocket queue for the task_group_id if it isn’t already created

Returns:

Status block containing “status” key.

Return type:

Batch instance

batch_run(batch) List[str]

Initiate a batch of tasks to funcX

Parameters:

batch (a Batch object) –

Returns:

task_ids

Return type:

a list of UUID strings that identify the tasks

register_endpoint(name, endpoint_id, metadata=None, multi_tenant=False)

Register an endpoint with the funcX service.

:param : :type : param name str Name of the endpoint :param : :type : param endpoint_id str The uuid of the endpoint :param : :type : param metadata dict endpoint metadata :param : :type : param multi_tenant bool Whether the endpoint supports multiple users

Returns:

{‘endpoint_id’<>,

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

Return type:

dict

get_containers(name, description=None)

Register a DLHub endpoint with the funcX service and get the containers to launch.

Parameters:
  • name (str) – Name of the endpoint

  • description (str) – Description of the endpoint

Returns:

The port to connect to and a list of containers

Return type:

int

get_container(container_uuid, container_type)

Get the details of a container for staging it locally.

Parameters:
  • container_uuid (str) – UUID of the container in question

  • container_type (str) – The type of containers that will be used (Singularity, Shifter, Docker)

Returns:

The details of the containers to deploy

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

Get a list of all endpoints owned by the current user across all systems.

Returns:

A list of dictionaries which contain endpoint info

Return type:

list

register_function(function, function_name=None, container_uuid=None, description=None, public=False, group=None, searchable=True) str

Register a function code with the funcX service.

Parameters:
  • function (Python Function) – The function to be registered for remote execution

  • function_name (str) – The entry point (function name) of the function. Default: None

  • container_uuid (str) – Container UUID from registration with funcX

  • description (str) – Description of the file

  • public (bool) – Whether or not the function is publicly accessible. Default = False

  • group (str) – A globus group uuid to share this function with

  • searchable (bool) – If true, the function will be indexed into globus search with the appropriate permissions

Returns:

function uuid – UUID identifier for the registered function

Return type:

str

search_function(q, offset=0, limit=10, advanced=False)

Search for function via the funcX service

Parameters:
  • q (str) – free-form query string

  • offset (int) – offset into total results

  • limit (int) – max number of results to return

  • advanced (bool) – allows elastic-search like syntax in query string

Return type:

FunctionSearchResults

search_endpoint(q, scope='all', owner_id=None)
Parameters:
  • q

  • scope (str) – Can be one of {‘all’, ‘my-endpoints’, ‘shared-with-me’}

  • owner_id – should be urn like f”urn:globus:auth:identity:{owner_uuid}”

register_container(location, container_type, name='', description='')

Register a container with the funcX service.

Parameters:
  • location (str) – The location of the container (e.g., its docker url). Required

  • container_type (str) – The type of containers that will be used (Singularity, Shifter, Docker). Required

  • name (str) – A name for the container. Default = ‘’

  • description (str) – A description to associate with the container. Default = ‘’

Returns:

The id of the container

Return type:

str

build_container(container_spec)

Submit a request to build a docker image based on a container spec. This container build service is based on repo2docker, so the spec reflects features supported by it.

Only members of a managed globus group are allowed to use this service at present. This call will throw a ContainerBuildForbidden exception if you are not a member of this group.

Parameters:

container_spec (funcx.sdk.container_spec.ContainerSpec) – Complete specification of what goes into the container

Returns:

UUID of the container which can be used to register your function

Return type:

str

Raises:

ContainerBuildForbidden – User is not in the globus group that protects the build

add_to_whitelist(endpoint_id, function_ids)

Adds the function to the endpoint’s whitelist

Parameters:
  • endpoint_id (str) – The uuid of the endpoint

  • function_ids (list) – A list of function id’s to be whitelisted

Returns:

The response of the request

Return type:

json

get_whitelist(endpoint_id)

List the endpoint’s whitelist

Parameters:

endpoint_id (str) – The uuid of the endpoint

Returns:

The response of the request

Return type:

json

delete_from_whitelist(endpoint_id, function_ids)

List the endpoint’s whitelist

Parameters:
  • endpoint_id (str) – The uuid of the endpoint

  • function_ids (list) – A list of function id’s to be whitelisted

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

class funcx.sdk.container_spec.ContainerSpec(name: Optional[str] = None, description: Optional[str] = None, apt: Optional[list[str]] = None, pip: Optional[list[str]] = None, conda: Optional[list[str]] = None, python_version: str = '3.7', payload_url: Optional[str] = None)

Construct a container spec to pass to service for build operation.

Parameters:
  • name (str) – Name of this container to be used inside funcx

  • description (str) – Description of the container inside funcx

  • apt (List[str]) – List of Ubuntu library packages to install in container

  • pip (List[str]) – List of Python libraries to install from pypi

  • conda (List[str]) – List of Conda packages to install

  • python_version (str) – Version of Python to build into image

  • payload_url (str) – GitHub repo or publicly readable zip file to copy into container