Globus Transfer

Client

The primary interface for the Globus Transfer API is the TransferClient class.

class globus_sdk.TransferClient(*, environment: Optional[str] = None, base_url: Optional[str] = None, authorizer: Optional[globus_sdk.authorizers.base.GlobusAuthorizer] = None, app_name: Optional[str] = None, transport_params: Optional[Dict] = None)[source]

Bases: globus_sdk.client.BaseClient

Client for the Globus Transfer API.

This class provides helper methods for most common resources in the REST API, and basic get, put, post, and delete methods from the base rest client that can be used to access any REST resource.

Detailed documentation is available in the official REST API documentation, which is linked to from the method documentation. Methods that allow arbitrary keyword arguments will pass the extra arguments as query parameters.

Parameters

authorizer (GlobusAuthorizer) – An authorizer instance used for all calls to Globus Transfer

Paginated Calls

Methods which support pagination can be called as paginated or unpaginated methods. If the method name is TransferClient.foo, the paginated version is TransferClient.paginated.foo. Using TransferClient.endpoint_search as an example:

from globus_sdk import TransferClient
tc = TransferClient(...)

# this is the unpaginated version
for x in tc.endpoint_search("tutorial"):
    print("Endpoint ID: {}".format(x["id"]))

# this is the paginated version
for page in tc.paginated.endpoint_search("testdata"):
    for x in page:
        print("Endpoint ID: {}".format(x["id"]))

Methods

get_endpoint(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /endpoint/<endpoint_id>

Parameters
  • endpoint_id (str or UUID) – ID of endpoint to lookup

  • query_params (dict, optional) – Any additional parameters will be passed through as query params.

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> endpoint = tc.get_endpoint(endpoint_id)
>>> print("Endpoint name:",
>>>       endpoint["display_name"] or endpoint["canonical_name"])

External Documentation

See Get Endpoint by ID in the API documentation for details.

update_endpoint(endpoint_id: Union[uuid.UUID, str], data: Dict[str, Any], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

PUT /endpoint/<endpoint_id>

Parameters
  • endpoint_id (str or UUID) – ID of endpoint to lookup

  • data (dict) – A partial endpoint document with fields to update

  • query_params (dict, optional) – Any additional parameters will be passed through as query params.

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> epup = dict(display_name="My New Endpoint Name",
>>>             description="Better Description")
>>> update_result = tc.update_endpoint(endpoint_id, epup)

External Documentation

See Update Endpoint by ID in the API documentation for details.

create_endpoint(data: Dict[str, Any]) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint/<endpoint_id>

Parameters

data (dict) – An endpoint document with fields for the new endpoint

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> ep_data = {
>>>   "DATA_TYPE": "endpoint",
>>>   "display_name": display_name,
>>>   "DATA": [
>>>     {
>>>       "DATA_TYPE": "server",
>>>       "hostname": "gridftp.example.edu",
>>>     },
>>>   ],
>>> }
>>> create_result = tc.create_endpoint(ep_data)
>>> endpoint_id = create_result["id"]

External Documentation

See Create Endpoint in the API documentation for details.

delete_endpoint(endpoint_id: Union[uuid.UUID, str]) globus_sdk.response.GlobusHTTPResponse[source]

DELETE /endpoint/<endpoint_id>

Parameters

endpoint_id (str or UUID) – ID of endpoint to delete

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> delete_result = tc.delete_endpoint(endpoint_id)

External Documentation

See Delete Endpoint by ID in the API documentation for details.

GET /endpoint_search?filter_fulltext=<filter_fulltext>&filter_scope=<filter_scope>
Parameters
  • filter_fulltext (str, optional) – The string to use in a full text search on endpoints. Effectively, the “search query” which is being requested. May be omitted with specific filter_scope values.

  • filter_scope (str, optional) – A “scope” within which to search for endpoints. This must be one of the limited and known names known to the service, which can be found documented in the External Documentation below. Defaults to searching all endpoints (in which case filter_fulltext is required)

  • filter_owner_id (str, optional) – Limit search to endpoints owned by the specified Globus Auth identity. Conflicts with scopes ‘my-endpoints’, ‘my-gcp-endpoints’, and ‘shared-by-me’.

  • filter_host_endpoint (str, optional) – Limit search to endpoints hosted by the specified endpoint. May cause BadRequest or PermissionDenied errors if the endpoint ID given is not valid for this operation.

  • filter_non_functional (bool, optional) – Limit search to endpoints which have the ‘non_functional’ flag set to True or False.

  • limit (int, optional) – limit the number of results

  • offset (int, optional) – offset used in paging

  • query_params (dict, optional) – Any additional parameters will be passed through as query params.

Examples

Search for a given string as a fulltext search:

>>> tc = globus_sdk.TransferClient(...)
>>> for ep in tc.endpoint_search('String to search for!'):
>>>     print(ep['display_name'])

Search for a given string, but only on endpoints that you own:

>>> for ep in tc.endpoint_search('foo', filter_scope='my-endpoints'):
>>>     print('{0} has ID {1}'.format(ep['display_name'], ep['id']))

It is important to be aware that the Endpoint Search API limits you to 1000 results for any search query.

Paginated Usage

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

>>> client.paginated.endpoint_search(...)

For more information, see how to make paginated calls.

External Documentation

See Endpoint Search in the API documentation for details.

endpoint_autoactivate(endpoint_id: Union[uuid.UUID, str], *, if_expires_in: Optional[int] = None, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint/<endpoint_id>/autoactivate

Parameters
  • endpoint_id (str or UUID) – The ID of the endpoint to autoactivate

  • if_expires_in (int, optional) – A number of seconds. Autoactivation will only be attempted if the current activation expires within this timeframe. Otherwise, autoactivation will succeed with a code of ‘AlreadyActivated’

  • query_params (dict, optional) – Any additional parameters will be passed through as query params.

The following example will try to “auto” activate the endpoint using a credential available from another endpoint or sign in by the user with the same identity provider, but only if the endpoint is not already activated or going to expire within an hour (3600 seconds). If that fails, direct the user to the globus website to perform activation:

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> r = tc.endpoint_autoactivate(ep_id, if_expires_in=3600)
>>> while (r["code"] == "AutoActivationFailed"):
>>>     print(
>>>         "Endpoint requires manual activation, please open "
>>>         "the following URL in a browser to activate the endpoint:"
>>>         f"https://app.globus.org/file-manager?origin_id={ep_id}"
>>>     )
>>>     input("Press ENTER after activating the endpoint:")
>>>     r = tc.endpoint_autoactivate(ep_id, if_expires_in=3600)

This is the recommended flow for most thick client applications, because many endpoints require activation via OAuth MyProxy, which must be done in a browser anyway. Web based clients can link directly to the URL.

You also might want messaging or logging depending on why and how the operation succeeded, in which case you’ll need to look at the value of the “code” field and either decide on your own messaging or use the response’s “message” field.

>>> tc = globus_sdk.TransferClient(...)
>>> r = tc.endpoint_autoactivate(ep_id, if_expires_in=3600)
>>> if r['code'] == 'AutoActivationFailed':
>>>     print('Endpoint({}) Not Active! Error! Source message: {}'
>>>           .format(ep_id, r['message']))
>>>     sys.exit(1)
>>> elif r['code'] == 'AutoActivated.CachedCredential':
>>>     print('Endpoint({}) autoactivated using a cached credential.'
>>>           .format(ep_id))
>>> elif r['code'] == 'AutoActivated.GlobusOnlineCredential':
>>>     print(('Endpoint({}) autoactivated using a built-in Globus '
>>>            'credential.').format(ep_id))
>>> elif r['code'] = 'AlreadyActivated':
>>>     print('Endpoint({}) already active until at least {}'
>>>           .format(ep_id, 3600))

External Documentation

See Autoactivate Endpoint in the API documentation for details.

endpoint_deactivate(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint/<endpoint_id>/deactivate

Parameters
  • endpoint_id (str or UUID) – The ID of the endpoint to deactivate

  • query_params (dict, optional) – Any additional parameters will be passed through as query params.

External Documentation

See Deactivate Endpoint in the API documentation for details.

endpoint_activate(endpoint_id: Union[uuid.UUID, str], *, requirements_data: Optional[dict], query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint/<endpoint_id>/activate

Parameters
  • endpoint_id (str or UUID) – The ID of the endpoint to activate

  • query_params (dict, optional) – Any additional parameters will be passed through as query params.

Pram requirements_data

Filled in activation requirements data, as can be fetched from endpoint_get_activation_requirements(). Only the fields for the activation type being used need to be filled in.

Consider using autoactivate and web activation instead, described in the example for endpoint_autoactivate().

External Documentation

See Activate Endpoint in the API documentation for details.

endpoint_get_activation_requirements(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.activation.ActivationRequirementsResponse[source]

GET /endpoint/<endpoint_id>/activation_requirements

Parameters
  • endpoint_id (str or UUID) – The ID of the endpoint whose activation requirements data is being looked up

  • query_params (dict, optional) – Any additional parameters will be passed through as query params.

External Documentation

See Get Activation Requirements in the API documentation for details.

my_effective_pause_rule_list(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /endpoint/<endpoint_id>/my_effective_pause_rule_list

Parameters
  • endpoint_id (str or UUID) – the endpoint on which the current user’s effective pause rules are fetched

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get my effective endpoint pause rules in the API documentation for details.

my_shared_endpoint_list(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /endpoint/<endpoint_id>/my_shared_endpoint_list

Parameters
  • endpoint_id (str or UUID) – the host endpoint whose shares are listed

  • query_params (dict, optional) – Additional passthrough query parameters

Get a list of shared endpoints for which the user has administrator or access_manager on a given host endpoint.

External Documentation

See Get shared endpoint list in the API documentation for details.

get_shared_endpoint_list(endpoint_id: Union[uuid.UUID, str], *, max_results: Optional[int] = None, next_token: Optional[str] = None, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /endpoint/<endpoint_id>/shared_endpoint_list

Parameters
  • endpoint_id (str or UUID) – the host endpoint whose shares are listed

  • max_results (int, optional) – cap to the number of results

  • next_token (str, optional) – token used for paging

  • query_params – Any additional parameters will be passed through as query params.

Get a list of all shared endpoints on a given host endpoint.

Paginated Usage

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

>>> client.paginated.get_shared_endpoint_list(...)

For more information, see how to make paginated calls.

External Documentation

See Get shared endpoint list (2) in the API documentation for details.

create_shared_endpoint(data: Dict[str, Any]) globus_sdk.response.GlobusHTTPResponse[source]

POST /shared_endpoint

Parameters

data (dict) – A python dict representation of a shared_endpoint document

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> shared_ep_data = {
>>>   "DATA_TYPE": "shared_endpoint",
>>>   "host_endpoint": host_endpoint_id,
>>>   "host_path": host_path,
>>>   "display_name": display_name,
>>>   # optionally specify additional endpoint fields
>>>   "description": "my test share"
>>> }
>>> create_result = tc.create_shared_endpoint(shared_ep_data)
>>> endpoint_id = create_result["id"]

External Documentation

See Create Shared Endpoint in the API documentation for details.

endpoint_server_list(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /endpoint/<endpoint_id>/server_list

Parameters

endpoint_id (str or UUID) – The endpoint whose servers are being listed

External Documentation

See Get endpoint server list in the API documentation for details.

get_endpoint_server(endpoint_id: Union[uuid.UUID, str], server_id: Union[int, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /endpoint/<endpoint_id>/server/<server_id>

Parameters
  • endpoint_id (str or UUID) – The endpoint under which the server is registered

  • server_id (str or int) – The ID of the server

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get endpoint server by id in the API documentation for details.

add_endpoint_server(endpoint_id: Union[uuid.UUID, str], server_data: Dict[str, Any]) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint/<endpoint_id>/server

Parameters
  • endpoint_id (str or UUID) – The endpoint under which the server is being registered

  • server_data (dict) – Fields for the new server, as a server document

External Documentation

See Add endpoint server in the API documentation for details.

update_endpoint_server(endpoint_id: Union[uuid.UUID, str], server_id: Union[int, str], server_data: Dict[str, Any]) globus_sdk.response.GlobusHTTPResponse[source]

PUT /endpoint/<endpoint_id>/server/<server_id>

Parameters
  • endpoint_id (str or UUID) – The endpoint under which the server is registered

  • server_id (str or int) – The ID of the server to update

  • server_data (dict) – Fields on the server to update, as a partial server document

External Documentation

See Update endpoint server by ID in the API documentation for details.

delete_endpoint_server(endpoint_id: Union[uuid.UUID, str], server_id: Union[int, str]) globus_sdk.response.GlobusHTTPResponse[source]

DELETE /endpoint/<endpoint_id>/server/<server_id>

Parameters
  • endpoint_id (str or UUID) – The endpoint under which the server is registered

  • server_id (str or int) – The ID of the server to delete

External Documentation

See Delete endpoint server by ID in the API documentation for details.

endpoint_role_list(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /endpoint/<endpoint_id>/role_list

Parameters

endpoint_id (str or UUID) – The endpoint whose roles are being listed

External Documentation

See Get list of endpoint roles in the API documentation for details.

add_endpoint_role(endpoint_id: Union[uuid.UUID, str], role_data: Dict[str, Any]) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint/<endpoint_id>/role

Parameters
  • endpoint_id (str or UUID) – The endpoint on which the role is being added

  • role_data (dict) – A role document for the new role

External Documentation

See Create endpoint role in the API documentation for details.

get_endpoint_role(endpoint_id: Union[uuid.UUID, str], role_id: str, *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /endpoint/<endpoint_id>/role/<role_id>

Parameters
  • endpoint_id (str or UUID) – The endpoint on which the role applies

  • role_id (str) – The ID of the role

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get endpoint role by ID in the API documentation for details.

delete_endpoint_role(endpoint_id: Union[uuid.UUID, str], role_id: str) globus_sdk.response.GlobusHTTPResponse[source]

DELETE /endpoint/<endpoint_id>/role/<role_id>

Parameters
  • endpoint_id (str or UUID) – The endpoint on which the role applies

  • role_id (str) – The ID of the role to delete

External Documentation

See Delete endpoint role by ID in the API documentation for details.

endpoint_acl_list(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /endpoint/<endpoint_id>/access_list

Parameters
  • endpoint_id (str or UUID) – The endpoint whose ACLs are being listed

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get list of access rules in the API documentation for details.

get_endpoint_acl_rule(endpoint_id: Union[uuid.UUID, str], rule_id: str, *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /endpoint/<endpoint_id>/access/<rule_id>

Parameters
  • endpoint_id (str or UUID) – The endpoint on which the access rule applies

  • rule_id (str) – The ID of the rule to fetch

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get access rule by ID in the API documentation for details.

add_endpoint_acl_rule(endpoint_id: Union[uuid.UUID, str], rule_data: Dict[str, Any]) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint/<endpoint_id>/access

Parameters
  • endpoint_id (str) – ID of endpoint to which to add the acl

  • rule_data (dict) – A python dict representation of an access document

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> rule_data = {
>>>   "DATA_TYPE": "access",
>>>   "principal_type": "identity",
>>>   "principal": identity_id,
>>>   "path": "/dataset1/",
>>>   "permissions": "rw",
>>> }
>>> result = tc.add_endpoint_acl_rule(endpoint_id, rule_data)
>>> rule_id = result["access_id"]

Note that if this rule is being created on a shared endpoint the “path” field is relative to the “host_path” of the shared endpoint.

External Documentation

See Create access rule in the API documentation for details.

update_endpoint_acl_rule(endpoint_id: Union[uuid.UUID, str], rule_id: str, rule_data: Dict[str, Any]) globus_sdk.response.GlobusHTTPResponse[source]

PUT /endpoint/<endpoint_id>/access/<rule_id>

Parameters
  • endpoint_id (str or UUID) – The endpoint on which the access rule applies

  • rule_id (str) – The ID of the access rule to modify

  • rule_data (dict) – A partial access document containing fields to update

External Documentation

See Update access rule in the API documentation for details.

delete_endpoint_acl_rule(endpoint_id: Union[uuid.UUID, str], rule_id: str) globus_sdk.response.GlobusHTTPResponse[source]

DELETE /endpoint/<endpoint_id>/access/<rule_id>

Parameters
  • endpoint_id (str or UUID) – The endpoint on which the access rule applies

  • rule_id (str) – The ID of the access rule to remove

External Documentation

See Delete access rule in the API documentation for details.

bookmark_list(*, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /bookmark_list

Parameters

query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get list of bookmarks in the API documentation for details.

create_bookmark(bookmark_data: Dict[str, Any]) globus_sdk.response.GlobusHTTPResponse[source]

POST /bookmark

Parameters

bookmark_data (dict) – A bookmark document for the bookmark to create

External Documentation

See Create bookmark in the API documentation for details.

get_bookmark(bookmark_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /bookmark/<bookmark_id>

Parameters
  • bookmark_id (str or UUID) – The ID of the bookmark to lookup

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get bookmark by ID in the API documentation for details.

update_bookmark(bookmark_id: Union[uuid.UUID, str], bookmark_data: Dict[str, Any]) globus_sdk.response.GlobusHTTPResponse[source]

PUT /bookmark/<bookmark_id>

Parameters
  • bookmark_id (str or UUID) – The ID of the bookmark to modify

  • bookmark_data (dict) – A partial bookmark document with fields to update

External Documentation

See Update bookmark in the API documentation for details.

delete_bookmark(bookmark_id: Union[uuid.UUID, str]) globus_sdk.response.GlobusHTTPResponse[source]

DELETE /bookmark/<bookmark_id>

Parameters

bookmark_id (str or UUID) – The ID of the bookmark to delete

External Documentation

See Delete bookmark by ID in the API documentation for details.

operation_ls(endpoint_id: Union[uuid.UUID, str], path: Optional[str] = None, *, show_hidden: Optional[bool] = None, orderby: Optional[Union[str, List[str]]] = None, filter: Optional[str] = None, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /operation/endpoint/<endpoint_id>/ls

Parameters
  • endpoint_id (str or UUID) – The ID of the endpoint on which to do a dir listing

  • path (str, optional) – Path to a directory on the endpoint to list

  • show_hidden (bool, optional) – Show hidden files (names beginning in dot). Defaults to true.

  • orderby (str, optional) – One or more order-by options. Each option is either a field name or a field name followed by a space and ‘ASC’ or ‘DESC’ for ascending or descending.

  • filter (str, optional) – Only return file documents that match these filter clauses. For the filter syntax, see the External Documentation linked below.

  • query_params (dict, optional) – Additional passthrough query parameters

Examples

List with a path:

>>> tc = globus_sdk.TransferClient(...)
>>> for entry in tc.operation_ls(ep_id, path="/~/project1/"):
>>>     print(entry["name"], entry["type"])

List with explicit ordering:

>>> tc = globus_sdk.TransferClient(...)
>>> for entry in tc.operation_ls(
>>>     ep_id,
>>>     path="/~/project1/",
>>>     orderby=["type", "name"]
>>> ):
>>>     print(entry["name DESC"], entry["type"])

External Documentation

See List Directory Contents in the API documentation for details.

operation_mkdir(endpoint_id: Union[uuid.UUID, str], path: str, *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

POST /operation/endpoint/<endpoint_id>/mkdir

Parameters
  • endpoint_id (str or UUID) – The ID of the endpoint on which to create a directory

  • path (str) – Path to the new directory to create

  • query_params (dict, optional) – Additional passthrough query parameters

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> tc.operation_mkdir(ep_id, path="/~/newdir/")

External Documentation

See Make Directory in the API documentation for details.

operation_rename(endpoint_id: Union[uuid.UUID, str], oldpath: str, newpath: str, *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

POST /operation/endpoint/<endpoint_id>/rename

Parameters
  • endpoint_id (str or UUID) – The ID of the endpoint on which to rename a file

  • oldpath (str) – Path to the old filename

  • newpath (str) – Path to the new filename

  • query_params (dict, optional) – Additional passthrough query parameters

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> tc.operation_rename(ep_id, oldpath="/~/file1.txt",
>>>                     newpath="/~/project1data.txt")

External Documentation

See Rename in the API documentation for details.

POST /operation/endpoint/<endpoint_id>/symlink

Parameters
  • endpoint_id (str or UUID) – The ID of the endpoint on which to create a symlink

  • symlink_target (str) – The path referenced by the new symlink

  • path (str) – The name of (path to) the new symlink

  • query_params (dict, optional) – Additional passthrough query parameters

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> tc.operation_symlink(ep_id, symlink_target="/~/file1.txt",
>>>                      path="/~/link-to-file1.txt")

External Documentation

See Symlink in the API documentation for details.

get_submission_id(*, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /submission_id

Parameters

query_params (dict, optional) – Additional passthrough query parameters

Submission IDs are required to submit tasks to the Transfer service via the submit_transfer and submit_delete methods.

Most users will not need to call this method directly, as the convenience classes TransferData and DeleteData will call it automatically if they are not passed a submission_id explicitly.

External Documentation

See Get a submission ID in the API documentation for details.

submit_transfer(data: Union[Dict[str, Any], globus_sdk.services.transfer.data.transfer_data.TransferData]) globus_sdk.response.GlobusHTTPResponse[source]

POST /transfer

Parameters

data (dict or TransferData) – A transfer task document listing files and directories, and setting various options. See TransferData for details

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> tdata = globus_sdk.TransferData(tc, source_endpoint_id,
>>>                                 destination_endpoint_id,
>>>                                 label="SDK example",
>>>                                 sync_level="checksum")
>>> tdata.add_item("/source/path/dir/", "/dest/path/dir/",
>>>                recursive=True)
>>> tdata.add_item("/source/path/file.txt",
>>>                "/dest/path/file.txt")
>>> transfer_result = tc.submit_transfer(tdata)
>>> print("task_id =", transfer_result["task_id"])

The data parameter can be a normal Python dictionary, or a TransferData object.

External Documentation

See Submit a transfer task in the API documentation for details.

submit_delete(data: Union[Dict[str, Any], globus_sdk.services.transfer.data.delete_data.DeleteData]) globus_sdk.response.GlobusHTTPResponse[source]

POST /delete

Parameters

data (dict or DeleteData) – A delete task document listing files and directories, and setting various options. See DeleteData for details

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> ddata = globus_sdk.DeleteData(tc, endpoint_id, recursive=True)
>>> ddata.add_item("/dir/to/delete/")
>>> ddata.add_item("/file/to/delete/file.txt")
>>> delete_result = tc.submit_delete(ddata)
>>> print("task_id =", delete_result["task_id"])

The data parameter can be a normal Python dictionary, or a DeleteData object.

External Documentation

See Submit a delete task in the API documentation for details.

task_list(*, limit: Optional[int] = None, offset: Optional[int] = None, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /task_list

Get an iterable of task documents owned by the current user.

Parameters
  • limit (int, optional) – limit the number of results

  • offset (int, optional) – offset used in paging

  • query_params (dict, optional) – Additional passthrough query parameters

Examples

Fetch 10 tasks and print some basic info:

>>> tc = TransferClient(...)
>>> for task in tc.task_list(limit=10):
>>>     print("Task({}): {} -> {}".format(
>>>         task["task_id"], task["source_endpoint"],
>>>         task["destination_endpoint"]))

Paginated Usage

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

>>> client.paginated.task_list(...)

For more information, see how to make paginated calls.

External Documentation

See Task list in the API documentation for details.

task_event_list(task_id: Union[uuid.UUID, str], *, limit: Optional[int] = None, offset: Optional[int] = None, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /task/<task_id>/event_list

List events (for example, faults and errors) for a given Task.

Parameters
  • task_id (str or UUID) – The ID of the task to inspect

  • limit (int, optional) – limit the number of results

  • offset (int, optional) – offset used in paging

  • query_params (dict, optional) – Additional passthrough query parameters

Examples

Fetch 10 events and print some basic info:

>>> tc = TransferClient(...)
>>> task_id = ...
>>> for event in tc.task_event_list(task_id, limit=10):
>>>     print("Event on Task({}) at {}:\n{}".format(
>>>         task_id, event["time"], event["description"])

Paginated Usage

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

>>> client.paginated.task_event_list(...)

For more information, see how to make paginated calls.

External Documentation

See Get event list in the API documentation for details.

get_task(task_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /task/<task_id>

Parameters
  • task_id (str or UUID) – The ID of the task to inspect

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get task by ID in the API documentation for details.

update_task(task_id: Union[uuid.UUID, str], data: Dict[str, Any], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

PUT /task/<task_id>

Modify a task. Only tasks which are still running can be modified, and only the label and deadline fields can be updated.

Parameters
  • task_id (str or UUID) – The ID of the task to modify

  • data (dict) – A partial task document with fields to update

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Update task by ID in the API documentation for details.

cancel_task(task_id: Union[uuid.UUID, str]) globus_sdk.response.GlobusHTTPResponse[source]

POST /task/<task_id>/cancel

Cancel a task which is still running.

Parameters

task_id (str or UUID) – The ID of the task to cancel

External Documentation

See Cancel task by ID in the API documentation for details.

task_wait(task_id: Union[uuid.UUID, str], *, timeout: int = 10, polling_interval: int = 10) bool[source]

Wait until a Task is complete or fails, with a time limit. If the task is “ACTIVE” after time runs out, returns False. Otherwise returns True.

Parameters
  • task_id (str or UUID) – ID of the Task to wait on for completion

  • timeout (int, optional) – Number of seconds to wait in total. Minimum 1. [Default: 10]

  • polling_interval (int, optional) – Number of seconds between queries to Globus about the Task status. Minimum 1. [Default: 10]

Examples

If you want to wait for a task to terminate, but want to warn every minute that it doesn’t terminate, you could:

>>> tc = TransferClient(...)
>>> while not tc.task_wait(task_id, timeout=60):
>>>     print("Another minute went by without {0} terminating"
>>>           .format(task_id))

Or perhaps you want to check on a task every minute for 10 minutes, and give up if it doesn’t complete in that time:

>>> tc = TransferClient(...)
>>> done = tc.task_wait(task_id, timeout=600, polling_interval=60):
>>> if not done:
>>>     print("{0} didn't successfully terminate!"
>>>           .format(task_id))
>>> else:
>>>     print("{0} completed".format(task_id))

You could print dots while you wait for a task by only waiting one second at a time:

>>> tc = TransferClient(...)
>>> while not tc.task_wait(task_id, timeout=1, polling_interval=1):
>>>     print(".", end="")
>>> print("\n{0} completed!".format(task_id))
task_pause_info(task_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /task/<task_id>/pause_info

Get info about why a task is paused or about to be paused.

Parameters
  • task_id (str or UUID) – The ID of the task to inspect

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get task pause info in the API documentation for details.

task_successful_transfers(task_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /task/<task_id>/successful_transfers

Get the successful file transfers for a completed Task.

Note

Only files that were actually transferred are included. This does not include directories, files that were checked but skipped as part of a sync transfer, or files which were skipped due to skip_source_errors being set on the task.

Parameters
  • task_id (str or UUID) – The ID of the task to inspect

  • query_params (dict, optional) – Additional passthrough query parameters

Examples

Fetch all transferred files for a task and print some basic info:

>>> tc = TransferClient(...)
>>> task_id = ...
>>> for info in tc.task_successful_transfers(task_id):
>>>     print("{} -> {}".format(
>>>         info["source_path"], info["destination_path"]))

Paginated Usage

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

>>> client.paginated.task_successful_transfers(...)

For more information, see how to make paginated calls.

External Documentation

See Get Task Successful Transfer in the API documentation for details.

task_skipped_errors(task_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /task/<task_id>/skipped_errors

Get path and error information for all paths that were skipped due to skip_source_errors being set on a completed transfer Task.

Parameters
  • task_id (str or UUID) – The ID of the task to inspect

  • query_params (dict, optional) – Additional passthrough query parameters

Examples

Fetch all skipped errors for a task and print some basic info:

>>> tc = TransferClient(...)
>>> task_id = ...
>>> for info in tc.task_skipped_errors(task_id):
>>>     print("{} -> {}".format(
>>>         info["error_code"], info["source_path"]))

Paginated Usage

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

>>> client.paginated.task_skipped_errors(...)

For more information, see how to make paginated calls.

External Documentation

See Get Task Skipped Errors in the API documentation for details.

endpoint_manager_monitored_endpoints(*, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET endpoint_manager/monitored_endpoints

Get endpoints the current user is a monitor or manager on.

Parameters

query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get monitored endpoints in the API documentation for details.

endpoint_manager_hosted_endpoint_list(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /endpoint_manager/endpoint/<endpoint_id>/hosted_endpoint_list

Get shared endpoints hosted on the given endpoint.

Parameters
  • endpoint_id (str or UUID) – The ID of the host endpoint

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get hosted endpoint list in the API documentation for details.

endpoint_manager_get_endpoint(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /endpoint_manager/endpoint/<endpoint_id>

Get endpoint details as an admin.

Parameters
  • endpoint_id (str or UUID) – The ID of the endpoint

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get endpoint as admin in the API documentation for details.

endpoint_manager_acl_list(endpoint_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET endpoint_manager/endpoint/<endpoint_id>/access_list

Get a list of access control rules on specified endpoint as an admin.

Parameters
  • endpoint_id (str or UUID) – The ID of the endpoint

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get endpoint access list as admin in the API documentation for details.

endpoint_manager_task_list(*, filter_status: Optional[Union[Iterable[str], str]] = None, filter_task_id: Optional[Union[Iterable[Union[uuid.UUID, str]], uuid.UUID, str]] = None, filter_owner_id: Optional[Union[uuid.UUID, str]] = None, filter_endpoint: Optional[Union[uuid.UUID, str]] = None, filter_is_paused: Optional[bool] = None, filter_completion_time: Union[None, str, Tuple[Union[str, datetime.datetime], Union[str, datetime.datetime]]] = None, filter_min_faults: Optional[int] = None, filter_local_user: Optional[str] = None, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET endpoint_manager/task_list

Get a list of tasks visible via activity_monitor role, as opposed to tasks owned by the current user.

For any query that doesn’t specify a filter_status that is a subset of ("ACTIVE", "INACTIVE"), at least one of filter_task_id or filter_endpoint is required.

Parameters
  • filter_status (str or iterable of str, optional) – Return only tasks with any of the specified statuses Note that in-progress tasks will have status "ACTIVE" or "INACTIVE", and completed tasks will have status "SUCCEEDED" or "FAILED".

  • filter_task_id (str, UUID, or iterable of str or UUID, optional) – Return only tasks with any of the specified ids. If any of the specified tasks do not involve an endpoint the user has an appropriate role for, a PermissionDenied error will be returned. This filter can’t be combined with any other filter. If another filter is passed, a BadRequest will be returned. (limit: 50 task IDs)

  • filter_owner_id (str or UUID, optional) – A Globus Auth identity id. Limit results to tasks submitted by the specified identity, or linked to the specified identity, at submit time. Returns UserNotFound if the identity does not exist or has never used the Globus Transfer service. If no tasks were submitted by this user to an endpoint the current user has an appropriate role on, an empty result set will be returned. Unless filtering for running tasks (i.e. filter_status is a subset of ("ACTIVE", "INACTIVE"), filter_endpoint is required when using filter_owner_id.

  • filter_endpoint (str or UUID, optional) – Single endpoint id. Return only tasks with a matching source or destination endpoint or matching source or destination host endpoint.

  • filter_is_paused (bool, optional) – Return only tasks with the specified is_paused value. Requires that filter_status is also passed and contains a subset of "ACTIVE" and "INACTIVE". Completed tasks always have is_paused equal to False and filtering on their paused state is not useful and not supported. Note that pausing is an async operation, and after a pause rule is inserted it will take time before the is_paused flag is set on all affected tasks. Tasks paused by id will have the is_paused flag set immediately.

  • filter_completion_time (str, tuple of str, or tuple of datetime, optional) – Start and end date-times separated by a comma, or provided as a tuple of strings or datetime objects. Returns only completed tasks with completion_time in the specified range. Date strings should be specified in one of the following ISO 8601 formats: YYYY-MM-DDTHH:MM:SS, YYYY-MM-DDTHH:MM:SS+/-HH:MM, or YYYY-MM-DDTHH:MM:SSZ. If no timezone is specified, UTC is assumed. A space can be used between the date and time instead of T. A blank string may be used for either the start or end (but not both) to indicate no limit on that side. If the end date is blank, the filter will also include all active tasks, since they will complete some time in the future.

  • filter_min_faults (int, optional) – Minimum number of cumulative faults, inclusive. Return only tasks with faults >= N, where N is the filter value. Use filter_min_faults=1 to find all tasks with at least one fault. Note that many errors are not fatal and the task may still be successful even if faults >= 1.

  • filter_local_user (str, optional) – A valid username for the target system running the endpoint, as a utf8 encoded string. Requires that filter_endpoint is also set. Return only tasks that have successfully fetched the local user from the endpoint, and match the values of filter_endpoint and filter_local_user on the source or on the destination.

  • query_params (dict, optional) – Additional passthrough query parameters

Examples

Fetch some tasks and print some basic info:

>>> tc = TransferClient(...)
>>> for task in tc.endpoint_manager_task_list(filter_status="ACTIVE"):
>>>     print("Task({}): {} -> {}\n  was submitted by\n  {}".format(
>>>         task["task_id"], task["source_endpoint"],
>>>         task["destination_endpoint"], task["owner_string"]))

Do that same operation on all tasks visible via activity_monitor status:

>>> tc = TransferClient(...)
>>> for page in tc.paginated.endpoint_manager_task_list(
>>>     filter_status="ACTIVE"
>>> ):
>>>     for task in page:
>>>         print("Task({}): {} -> {}\n  was submitted by\n  {}".format(
>>>             task["task_id"], task["source_endpoint"],
>>>             task["destination_endpoint"), task["owner_string"])

Paginated Usage

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

>>> client.paginated.endpoint_manager_task_list(...)

For more information, see how to make paginated calls.

External Documentation

See Advanced Endpoint Management: Get tasks in the API documentation for details.

endpoint_manager_get_task(task_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /endpoint_manager/task/<task_id>

Get task info as an admin. Requires activity monitor effective role on the destination endpoint of the task.

Parameters
  • task_id (str or UUID) – The ID of the task to inspect

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get task as admin in the API documentation for details.

endpoint_manager_task_event_list(task_id: Union[uuid.UUID, str], *, limit: Optional[int] = None, offset: Optional[int] = None, filter_is_error: Optional[bool] = None, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /task/<task_id>/event_list

List events (for example, faults and errors) for a given task as an admin. Requires activity monitor effective role on the destination endpoint of the task.

Parameters
  • task_id (str or UUID) – The ID of the task to inspect

  • limit (int, optional) – limit the number of results

  • offset – offset used in paging

  • filter_is_error (bool, optional) – Return only events that are errors. A value of False (returning only non-errors) is not supported. By default all events are returned.

  • query_params (dict, optional) – Additional passthrough query parameters

Paginated Usage

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

>>> client.paginated.endpoint_manager_task_event_list(...)

For more information, see how to make paginated calls.

External Documentation

See Get task events as admin in the API documentation for details.

endpoint_manager_task_pause_info(task_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /endpoint_manager/task/<task_id>/pause_info

Get details about why a task is paused as an admin. Requires activity monitor effective role on the destination endpoint of the task.

Parameters
  • task_id (str or UUID) – The ID of the task to inspect

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get task pause info as admin in the API documentation for details.

endpoint_manager_task_successful_transfers(task_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /endpoint_manager/task/<task_id>/successful_transfers

Get the successful file transfers for a completed Task as an admin.

Parameters
  • task_id (str or UUID) – The ID of the task to inspect

  • query_params (dict, optional) – Additional passthrough query parameters

Paginated Usage

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

>>> client.paginated.endpoint_manager_task_successful_transfers(...)

For more information, see how to make paginated calls.

External Documentation

See Get task successful transfers as admin in the API documentation for details.

endpoint_manager_task_skipped_errors(task_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /endpoint_manager/task/<task_id>/skipped_errors

Get skipped errors for a completed Task as an admin.

Parameters
  • task_id (str) – The ID of the task to inspect

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get task skipped errors as admin in the API documentation for details.

endpoint_manager_cancel_tasks(task_ids: Iterable[Union[uuid.UUID, str]], message: str, *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint_manager/admin_cancel

Cancel a list of tasks as an admin. Requires activity manager effective role on the task(s) source or destination endpoint(s).

Parameters
  • task_ids (iterable of str or UUID) – List of task ids to cancel

  • message (str) – Message given to all users whose tasks have been canceled

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Cancel tasks as admin in the API documentation for details.

endpoint_manager_cancel_status(admin_cancel_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /endpoint_manager/admin_cancel/<admin_cancel_id>

Get the status of an an admin cancel (result of endpoint_manager_cancel_tasks).

Parameters
  • admin_cancel_id (str or UUID) – The ID of the the cancel job to inspect

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get cancel status by ID in the API documentation for details.

endpoint_manager_pause_tasks(task_ids: Iterable[Union[uuid.UUID, str]], message: str, *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint_manager/admin_pause

Pause a list of tasks as an admin. Requires activity manager effective role on the task(s) source or destination endpoint(s).

Parameters
  • task_ids (iterable of str or UUID) – List of task ids to pause

  • message (str) – Message given to all users whose tasks have been paused

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Pause tasks as admin in the API documentation for details.

endpoint_manager_resume_tasks(task_ids: Iterable[Union[uuid.UUID, str]], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint_manager/admin_resume

Resume a list of tasks as an admin. Requires activity manager effective role on the task(s) source or destination endpoint(s).

Parameters
  • task_ids (iterable of str or UUID) – List of task ids to resume

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Resume tasks as admin in the API documentation for details.

endpoint_manager_pause_rule_list(*, filter_endpoint: Optional[Union[uuid.UUID, str]] = None, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.transfer.response.iterable.IterableTransferResponse[source]

GET /endpoint_manager/pause_rule_list

Get a list of pause rules on endpoints that the current user has the activity monitor effective role on.

Parameters
  • filter_endpoint (str) – An endpoint ID. Limit results to rules on endpoints hosted by this endpoint. Must be activity monitor on this endpoint, not just the hosted endpoints.

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get pause rules in the API documentation for details.

endpoint_manager_create_pause_rule(data: Optional[Dict[str, Any]]) globus_sdk.response.GlobusHTTPResponse[source]

POST /endpoint_manager/pause_rule

Create a new pause rule. Requires the activity manager effective role on the endpoint defined in the rule.

Parameters

data (dict) – A pause rule document describing the rule to create

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> rule_data = {
>>>   "DATA_TYPE": "pause_rule",
>>>   "message": "Message to users explaining why tasks are paused",
>>>   "endpoint_id": "339abc22-aab3-4b45-bb56-8d40535bfd80",
>>>   "identity_id": None,  # affect all users on endpoint
>>>   "start_time": None  # start now
>>> }
>>> create_result = tc.endpoint_manager_create_pause_rule(ep_data)
>>> rule_id = create_result["id"]

External Documentation

See Create pause rule in the API documentation for details.

endpoint_manager_get_pause_rule(pause_rule_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

GET /endpoint_manager/pause_rule/<pause_rule_id>

Get an existing pause rule by ID. Requires the activity manager effective role on the endpoint defined in the rule.

Parameters
  • pause_rule_id (str) – ID of pause rule to get

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Get pause rule in the API documentation for details.

endpoint_manager_update_pause_rule(pause_rule_id: Union[uuid.UUID, str], data: Optional[Dict[str, Any]]) globus_sdk.response.GlobusHTTPResponse[source]

PUT /endpoint_manager/pause_rule/<pause_rule_id>

Update an existing pause rule by ID. Requires the activity manager effective role on the endpoint defined in the rule. Note that non update-able fields in data will be ignored.

Parameters
  • pause_rule_id (str) – The ID of the pause rule to update

  • data (dict) – A partial pause rule document with fields to update

Examples

>>> tc = globus_sdk.TransferClient(...)
>>> rule_data = {
>>>   "message": "Update to pause, reads are now allowed.",
>>>   "pause_ls": False,
>>>   "pause_task_transfer_read": False
>>> }
>>> update_result = tc.endpoint_manager_update_pause_rule(ep_data)

External Documentation

See Update pause rule in the API documentation for details.

endpoint_manager_delete_pause_rule(pause_rule_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

DELETE /endpoint_manager/pause_rule/<pause_rule_id>

Delete an existing pause rule by ID. Requires the user to see the “editable” field of the rule as True. Any tasks affected by this rule will no longer be once it is deleted.

Parameters
  • pause_rule_id (str) – The ID of the pause rule to delete

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Delete pause rule in the API documentation for details.

Helper Objects

These helper objects make it easier to correctly create data for consumption by a TransferClient.

class globus_sdk.TransferData(transfer_client: globus_sdk.TransferClient, source_endpoint: Union[uuid.UUID, str], destination_endpoint: Union[uuid.UUID, str], *, label: Optional[str] = None, submission_id: Optional[Union[uuid.UUID, str]] = None, sync_level: Optional[str] = None, verify_checksum: bool = False, preserve_timestamp: bool = False, encrypt_data: bool = False, deadline: Optional[Union[str, datetime.datetime]] = None, skip_source_errors: bool = False, fail_on_quota_errors: bool = False, recursive_symlinks: str = 'ignore', delete_destination_extra: bool = False, additional_fields: Optional[Dict[str, Any]] = None)[source]

Bases: globus_sdk.utils.PayloadWrapper

Convenience class for constructing a transfer document, to use as the data parameter to submit_transfer.

At least one item must be added using add_item.

If submission_id isn’t passed, one will be fetched automatically. The submission ID can be pulled out of here to inspect, but the document can be used as-is multiple times over to retry a potential submission failure (so there shouldn’t be any need to inspect it).

Parameters
  • transfer_client (TransferClient) – A TransferClient instance which will be used to get a submission ID if one is not supplied. Should be the same instance that is used to submit the transfer.

  • source_endpoint (str or UUID) – The endpoint ID of the source endpoint

  • destination_endpoint (str or UUID) – The endpoint ID of the destination endpoint

  • label (str, optional) – A string label for the Task

  • submission_id (str or UUID, optional) – A submission ID value fetched via get_submission_id . Defaults to using transfer_client.get_submission_id

  • sync_level (int or str, optional) – The method used to compare items between the source and destination. One of "exists", "size", "mtime", or "checksum" See the section below on sync-level for an explanation of values.

  • verify_checksum (bool, optional) – When true, after transfer verify that the source and destination file checksums match. If they don’t, re-transfer the entire file and keep trying until it succeeds. This will create CPU load on both the origin and destination of the transfer, and may even be a bottleneck if the network speed is high enough. [default: False]

  • preserve_timestamp (bool, optional) – When true, Globus Transfer will attempt to set file timestamps on the destination to match those on the origin. [default: False]

  • encrypt_data (bool, optional) – When true, all files will be TLS-protected during transfer. [default: False]

  • deadline (str or datetime, optional) – An ISO-8601 timestamp (as a string) or a datetime object which defines a deadline for the transfer. At the deadline, even if the data transfer is not complete, the job will be canceled. We recommend ensuring that the timestamp is in UTC to avoid confusion and ambiguity. Examples of ISO-8601 timestamps include 2017-10-12 09:30Z, 2017-10-12 12:33:54+00:00, and 2017-10-12

  • recursive_symlinks (str) – Specify the behavior of recursive directory transfers when encountering symlinks. One of "ignore", "keep", or "copy". "ignore" skips symlinks, "keep" creates symlinks at the destination matching the source (without modifying the link path at all), and "copy" follows symlinks on the source, failing if the link is invalid. [default: "ignore"]

  • skip_source_errors (bool, optional) – When true, source permission denied and file not found errors from the source endpoint will cause the offending path to be skipped. [default: False]

  • fail_on_quota_errors (bool, optional) – When true, quota exceeded errors will cause the task to fail. [default: False]

  • delete_destination_extra – Delete files, directories, and symlinks on the destination endpoint which don’t exist on the source endpoint or are a different type. Only applies for recursive directory transfers. [default: False]

  • delete_destination_extra – bool, optional

  • additional_fields (dict, optional) – additional fields to be added to the transfer document. Mostly intended for internal use

Sync Levels

The values for sync_level are used to determine how comparisons are made between files found both on the source and the destination. When files match, no data transfer will occur.

For compatibility, this can be an integer 0, 1, 2, or 3 in addition to the string values.

The meanings are as follows:

value

behavior

0, exists

Determine whether or not to transfer based on file existence. If the destination file is absent, do the transfer.

1, size

Determine whether or not to transfer based on the size of the file. If destination file size does not match the source, do the transfer.

2, mtime

Determine whether or not to transfer based on modification times. If source has a newer modified time than the destination, do the transfer.

3, checksum

Determine whether or not to transfer based on checksums of file contents. If source and destination contents differ, as determined by a checksum of their contents, do the transfer.

Examples

See the submit_transfer documentation for example usage.

External Documentation

See the Task document definition and Transfer specific fields in the REST documentation for more details on Transfer Task documents.

Methods

add_item(source_path: str, destination_path: str, *, recursive: bool = False, external_checksum: Optional[str] = None, checksum_algorithm: Optional[str] = None, additional_fields: Optional[Dict[str, Any]] = None) None[source]

Add a file or directory to be transferred. If the item is a symlink to a file or directory, the file or directory at the target of the symlink will be transferred.

Appends a transfer_item document to the DATA key of the transfer document.

Note

The full path to the destination file must be provided for file items. Parent directories of files are not allowed. See task submission documentation for more details.

Parameters
  • source_path (str) – Path to the source directory or file to be transferred

  • destination_path (str) – Path to the source directory or file will be transferred to

  • recursive (bool) – Set to True if the target at source path is a directory

  • external_checksum (str, optional) – A checksum to verify both source file and destination file integrity. The checksum will be verified after the data transfer and a failure will cause the entire task to fail. Cannot be used with directories. Assumed to be an MD5 checksum unless checksum_algorithm is also given.

  • checksum_algorithm (str, optional) – Specifies the checksum algorithm to be used when verify_checksum is True, sync_level is “checksum” or 3, or an external_checksum is given.

Add a symlink to be transferred as a symlink rather than as the target of the symlink.

Appends a transfer_symlink_item document to the DATA key of the transfer document.

Parameters
  • source_path (str) – Path to the source symlink

  • destination_path (str) – Path to which the source symlink will be transferred

class globus_sdk.DeleteData(transfer_client: globus_sdk.TransferClient, endpoint: Union[uuid.UUID, str], *, label: Optional[str] = None, submission_id: Optional[Union[uuid.UUID, str]] = None, recursive: bool = False, deadline: Optional[Union[str, datetime.datetime]] = None, additional_fields: Optional[Dict[str, Any]] = None)[source]

Bases: globus_sdk.utils.PayloadWrapper

Convenience class for constructing a delete document, to use as the data parameter to submit_delete.

At least one item must be added using add_item.

If submission_id isn’t passed, one will be fetched automatically. The submission ID can be pulled out of here to inspect, but the document can be used as-is multiple times over to retry a potential submission failure (so there shouldn’t be any need to inspect it).

Parameters
  • transfer_client (TransferClient) – A TransferClient instance which will be used to get a submission ID if one is not supplied. Should be the same instance that is used to submit the deletion.

  • endpoint (str or UUID) – The endpoint ID which is targeted by this deletion Task

  • label (str, optional) – A string label for the Task

  • submission_id (str or UUID, optional) – A submission ID value fetched via get_submission_id. Defaults to using transfer_client.get_submission_id

  • recursive (bool) – Recursively delete subdirectories on the target endpoint [default: False]

  • deadline (str or datetime, optional) – An ISO-8601 timestamp (as a string) or a datetime object which defines a deadline for the deletion. At the deadline, even if the data deletion is not complete, the job will be canceled. We recommend ensuring that the timestamp is in UTC to avoid confusion and ambiguity. Examples of ISO-8601 timestamps include 2017-10-12 09:30Z, 2017-10-12 12:33:54+00:00, and 2017-10-12

  • additional_fields (dict, optional) – additional fields to be added to the delete document. Mostly intended for internal use

Examples

See the submit_delete documentation for example usage.

External Documentation

See the Task document definition and Delete specific fields in the REST documentation for more details on Delete Task documents.

Methods

add_item(path: str, *, additional_fields: Optional[Dict[str, Any]] = None) None[source]

Add a file or directory or symlink to be deleted. If any of the paths are directories, recursive must be set True on the top level DeleteData. Symlinks will never be followed, only deleted.

Appends a delete_item document to the DATA key of the delete document.

Client Errors

When an error occurs, a TransferClient will raise this specialized type of error, rather than a generic GlobusAPIError.

class globus_sdk.TransferAPIError(r: requests.models.Response)[source]

Bases: globus_sdk.exc.api.GlobusAPIError

Error class for the Transfer API client. In addition to the inherited code and message instance variables, provides request_id.

Variables

request_id – Unique identifier for the request, which should be provided when contacting support@globus.org.

Transfer Responses

class globus_sdk.services.transfer.response.ActivationRequirementsResponse(*args: Any, **kwargs: Any)[source]

Bases: globus_sdk.response.GlobusHTTPResponse

Response class for Activation Requirements responses.

All Activation Requirements documents refer to a specific Endpoint, from whence they were acquired. References to “the Endpoint” implicitly refer to that originating Endpoint, and not to some other Endpoint.

External Documentation

See Activation Requirements Document in the API documentation for details.

active_until(time_seconds: int, relative_time: bool = True) bool[source]

Check if the Endpoint will be active until some time in the future, given as an integer number of seconds. When relative_time=False, the time_seconds is interpreted as a POSIX timestamp.

This supports queries using both relative and absolute timestamps to better support a wide range of use cases. For example, if I have a task that I know will typically take N seconds, and I want an M second safety margin:

>>> num_secs_allowed = N + M
>>> tc = TransferClient(...)
>>> reqs_doc = tc.endpoint_get_activation_requirements(...)
>>> if not reqs_doc.active_until(num_secs_allowed):
>>>     raise Exception("Endpoint won't be active long enough")
>>> ...

or, alternatively, if I know that the endpoint must be active until October 18th, 2016 for my tasks to complete:

>>> oct18_2016 = 1476803436
>>> tc = TransferClient(...)
>>> reqs_doc = tc.endpoint_get_activation_requirements(...)
>>> if not reqs_doc.active_until(oct18_2016, relative_time=False):
>>>     raise Exception("Endpoint won't be active long enough")
>>> ...
Parameters
  • time_seconds (int) – Number of seconds into the future.

  • relative_time (bool) – Defaults to True. When False, time_seconds is treated as a POSIX timestamp (i.e. seconds since epoch as an integer) instead of its ordinary behavior.

Returns

True if the Endpoint will be active until the deadline, False otherwise

Return type

bool

property always_activated: bool

Returns True if the endpoint activation never expires (e.g. shared endpoints, globus connect personal endpoints).

Return type

bool

property supports_auto_activation: bool

Check if the document lists Auto-Activation as an available type of activation. Typically good to use when you need to catch endpoints that require web activation before proceeding.

>>> endpoint_id = "..."
>>> tc = TransferClient(...)
>>> reqs_doc = tc.endpoint_get_activation_requirements(endpoint_id)
>>> if not reqs_doc.supports_auto_activation:
>>>     # use `from __future__ import print_function` in py2
>>>     print(("This endpoint requires web activation. "
>>>            "Please login and activate the endpoint here:\n"
>>>            "https://app.globus.org/file-manager?origin_id={}")
>>>           .format(endpoint_id), file=sys.stderr)
>>>     # py3 calls it `input()` in py2, use `raw_input()`
>>>     input("Please Hit Enter When You Are Done")
Return type

bool

property supports_web_activation: bool

Check if the document lists known types of activation that can be done through the web. If this returns False, it means that the endpoint is of a highly unusual type, and you should directly inspect the response’s data attribute to see what is required. Sending users to the web page for activation is also a fairly safe action to take. Note that ActivationRequirementsResponse.supports_auto_activation directly implies ActivationRequirementsResponse.supports_web_activation, so these are not exclusive.

For example,

>>> tc = TransferClient(...)
>>> reqs_doc = tc.endpoint_get_activation_requirements(...)
>>> if not reqs_doc.supports_web_activation:
>>>     # use `from __future__ import print_function` in py2
>>>     print("Highly unusual endpoint. " +
>>>           "Cannot webactivate. Raw doc: " +
>>>           str(reqs_doc), file=sys.stderr)
>>>     print("Sending user to web anyway, just in case.",
>>>           file=sys.stderr)
>>> ...
Return type

bool

class globus_sdk.services.transfer.response.IterableTransferResponse(response: Union[requests.models.Response, GlobusHTTPResponse], client: Optional[globus_sdk.BaseClient] = None, *, iter_key: Optional[str] = None)[source]

Bases: globus_sdk.response.IterableResponse

Response class for non-paged list oriented resources. Allows top level fields to be accessed normally via standard item access, and also provides a convenient way to iterate over the sub-item list in a specified key:

>>> print("Path:", r["path"])
>>> # Equivalent to: for item in r["DATA"]
>>> for item in r:
>>>     print(item["name"], item["type"])