Globus Transfer#

Client#

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

class globus_sdk.TransferClient(*, environment=None, base_url=None, authorizer=None, app_name=None, transport_params=None)[source]#

Bases: 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.

Filter Formatting

Several methods of TransferClient take a filter parameter which can be a string, dict, or list of strings/dicts. When the filter given is a string, it is passed as a single unmodified param. When the filter given is a dict, it is formatted according to the below rules into a single param. When the filter is a list, each item of the list is parsed and passed as separate params.

dict parsing rules:

  • each (key, value) pair in the dict is a clause in the resulting filter string

  • clauses are each formatted to key:value

  • when the value is a list, it is comma-separated, as in key:value1,value2

  • clauses are separated with slashes, as in key1:value1/key2:value2

The corresponding external API documentation describes, in detail, the supported filter clauses for each method which uses the filter parameter. Generally, speaking, filter clauses documented as string list can be passed as lists to a filter dict, while string, date, and numeric filters should be passed as strings.

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

transport_class#

alias of TransferRequestsTransport

scopes: ScopeBuilder | None = <globus_sdk.scopes.builder.ScopeBuilder object>#

the scopes for this client may be present as a ScopeBuilder

get_endpoint(endpoint_id, *, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – ID of endpoint to lookup

  • query_params (dict[str, Any] | None) – Any additional parameters will be passed through as query params.

Return type:

GlobusHTTPResponse

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

GET /endpoint/<endpoint_id>

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

update_endpoint(endpoint_id, data, *, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – ID of endpoint to lookup

  • data (dict[str, Any]) – A partial endpoint document with fields to update

  • query_params (dict[str, Any] | None) – Any additional parameters will be passed through as query params.

Return type:

GlobusHTTPResponse

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

PUT /endpoint/<endpoint_id>

See Update Globus Connect Personal collection by id in the API documentation for details.

create_endpoint(data)[source]#

Warning

This method is deprecated with the end of Globus Connect Server v4 support and may no longer function with the Transfer API.

Parameters:

data (dict[str, Any]) – An endpoint document with fields for the new endpoint

Return type:

GlobusHTTPResponse

delete_endpoint(endpoint_id)[source]#
Parameters:

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

Return type:

GlobusHTTPResponse

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

DELETE /endpoint/<endpoint_id>

See Delete Globus Connect Personal collection by id in the API documentation for details.

Parameters:
  • filter_fulltext (str | None) – 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 | None) – 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 | None) – 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 (UUID | str | None) – 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 | None) – Limit search to endpoints which have the ‘non_functional’ flag set to True or False.

  • limit (int | None) – limit the number of results

  • offset (int | None) – offset used in paging

  • query_params (dict[str, Any] | None) – Any additional parameters will be passed through as query params.

Return type:

IterableTransferResponse

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

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(f"{ep['display_name']} has ID {ep['id']}")

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.

GET /endpoint_search?filter_fulltext=<filter_fulltext>&filter_scope=<filter_scope>

See Endpoint and Collection Search in the API documentation for details.

endpoint_autoactivate(endpoint_id, *, if_expires_in=None, query_params=None)[source]#

Warning

This method is deprecated with the end of Globus Connect Server v4 support and may no longer function with the Transfer API.

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

  • if_expires_in (int | None) – 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[str, Any] | None) – Any additional parameters will be passed through as query params.

Return type:

GlobusHTTPResponse

endpoint_deactivate(endpoint_id, *, query_params=None)[source]#

Warning

This method is deprecated with the end of Globus Connect Server v4 support and may no longer function with the Transfer API.

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

  • query_params (dict[str, Any] | None) – Any additional parameters will be passed through as query params.

Return type:

GlobusHTTPResponse

endpoint_activate(endpoint_id, *, requirements_data, query_params=None)[source]#

Warning

This method is deprecated with the end of Globus Connect Server v4 support and may no longer function with the Transfer API.

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

  • requirements_data (dict[str, Any] | None) – An optional body for the request

  • query_params (dict[str, Any] | None) – 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.

Return type:

GlobusHTTPResponse

endpoint_get_activation_requirements(endpoint_id, *, query_params=None)[source]#

Warning

This method is deprecated with the end of Globus Connect Server v4 support and may no longer function with the Transfer API.

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

  • query_params (dict[str, Any] | None) – Any additional parameters will be passed through as query params.

Return type:

ActivationRequirementsResponse

my_effective_pause_rule_list(endpoint_id, *, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – the endpoint on which the current user’s effective pause rules are fetched

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

GET /endpoint/<endpoint_id>/my_effective_pause_rule_list

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

my_shared_endpoint_list(endpoint_id, *, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – the host endpoint whose shares are listed

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

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

GET /endpoint/<endpoint_id>/my_shared_endpoint_list

See Get my guest collection list in the API documentation for details.

get_shared_endpoint_list(endpoint_id, *, max_results=None, next_token=None, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – the host endpoint whose shares are listed

  • max_results (int | None) – cap to the number of results

  • next_token (str | None) – token used for paging

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params.

Return type:

IterableTransferResponse

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

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.

GET /endpoint/<endpoint_id>/shared_endpoint_list

See Get guest collection list in the API documentation for details.

create_shared_endpoint(data)[source]#
Parameters:

data (dict[str, Any]) – A python dict representation of a shared_endpoint document

Return type:

GlobusHTTPResponse

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"]

POST /shared_endpoint

See Create guest collection in the API documentation for details.

endpoint_server_list(endpoint_id, *, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – The endpoint whose servers are being listed

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params.

Return type:

IterableTransferResponse

GET /endpoint/<endpoint_id>/server_list

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

get_endpoint_server(endpoint_id, server_id, *, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – The endpoint under which the server is registered

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

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

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

add_endpoint_server(endpoint_id, server_data)[source]#

Warning

This method is deprecated with the end of Globus Connect Server v4 support and may no longer function with the Transfer API.

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

  • server_data (dict[str, Any]) – Fields for the new server, as a server document

Return type:

GlobusHTTPResponse

update_endpoint_server(endpoint_id, server_id, server_data)[source]#

Warning

This method is deprecated with the end of Globus Connect Server v4 support and may no longer function with the Transfer API.

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

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

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

Return type:

GlobusHTTPResponse

delete_endpoint_server(endpoint_id, server_id)[source]#

Warning

This method is deprecated with the end of Globus Connect Server v4 support and may no longer function with the Transfer API.

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

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

Return type:

GlobusHTTPResponse

endpoint_role_list(endpoint_id, *, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – The endpoint whose roles are being listed

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params.

Return type:

IterableTransferResponse

GET /endpoint/<endpoint_id>/role_list

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

add_endpoint_role(endpoint_id, role_data)[source]#
Parameters:
  • endpoint_id (UUID | str) – The endpoint on which the role is being added

  • role_data (dict[str, Any]) – A role document for the new role

Return type:

GlobusHTTPResponse

POST /endpoint/<endpoint_id>/role

See Create Globus Connect Personal collection role in the API documentation for details.

get_endpoint_role(endpoint_id, role_id, *, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – The endpoint on which the role applies

  • role_id (str) – The ID of the role

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

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

See Get role by id in the API documentation for details.

delete_endpoint_role(endpoint_id, role_id)[source]#
Parameters:
  • endpoint_id (UUID | str) – The endpoint on which the role applies

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

Return type:

GlobusHTTPResponse

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

See Delete Globus Connect Personal collection role by id in the API documentation for details.

endpoint_acl_list(endpoint_id, *, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – The endpoint whose ACLs are being listed

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

GET /endpoint/<endpoint_id>/access_list

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

get_endpoint_acl_rule(endpoint_id, rule_id, *, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – The endpoint on which the access rule applies

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

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

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

add_endpoint_acl_rule(endpoint_id, rule_data)[source]#
Parameters:
  • endpoint_id (UUID | str) – ID of endpoint to which to add the acl

  • rule_data (dict[str, Any]) – A python dict representation of an access document

Return type:

GlobusHTTPResponse

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.

POST /endpoint/<endpoint_id>/access

See Create access rule in the API documentation for details.

update_endpoint_acl_rule(endpoint_id, rule_id, rule_data)[source]#
Parameters:
  • endpoint_id (UUID | str) – The endpoint on which the access rule applies

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

  • rule_data (dict[str, Any]) – A partial access document containing fields to update

Return type:

GlobusHTTPResponse

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

See Update access rule in the API documentation for details.

delete_endpoint_acl_rule(endpoint_id, rule_id)[source]#
Parameters:
  • endpoint_id (UUID | str) – The endpoint on which the access rule applies

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

Return type:

GlobusHTTPResponse

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

See Delete access rule in the API documentation for details.

bookmark_list(*, query_params=None)[source]#
Parameters:

query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

GET /bookmark_list

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

create_bookmark(bookmark_data)[source]#
Parameters:

bookmark_data (dict[str, Any]) – A bookmark document for the bookmark to create

Return type:

GlobusHTTPResponse

POST /bookmark

See Create bookmark in the API documentation for details.

get_bookmark(bookmark_id, *, query_params=None)[source]#
Parameters:
  • bookmark_id (UUID | str) – The ID of the bookmark to lookup

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /bookmark/<bookmark_id>

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

update_bookmark(bookmark_id, bookmark_data)[source]#
Parameters:
  • bookmark_id (UUID | str) – The ID of the bookmark to modify

  • bookmark_data (dict[str, Any]) – A partial bookmark document with fields to update

Return type:

GlobusHTTPResponse

PUT /bookmark/<bookmark_id>

See Update bookmark in the API documentation for details.

delete_bookmark(bookmark_id)[source]#
Parameters:

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

Return type:

GlobusHTTPResponse

DELETE /bookmark/<bookmark_id>

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

operation_ls(endpoint_id, path=None, *, show_hidden=None, orderby=None, limit=None, offset=None, filter=None, local_user=None, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – The ID of the endpoint on which to do a dir listing

  • path (str | None) – Path to a directory on the endpoint to list

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

  • limit (int | None) – Limit the number of results returned. Defaults to 100,000 , which is also the maximum.

  • offset (int | None) – Offset into the result list, which can be used to page results.

  • orderby (str | list[str] | None) – 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 | Dict[str, str | List[str]] | list[str | Dict[str, str | List[str]]] | None) – Only return file documents which match these filter clauses. For the filter syntax, see the External Documentation linked below. If a dict is supplied as the filter, it is formatted as a set of filter clauses. If a list is supplied, it is passed as multiple params. See filter formatting for details.

  • local_user (str | None) – Optional value passed to identity mapping specifying which local user account to map to. Only usable with Globus Connect Server v5 mapped collections.

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

Note

Pagination is not supported by the GridFTP protocol, and therefore limit+offset pagination will result in the Transfer service repeatedly fetching an entire directory listing from the server and filtering it before returning it to the client.

For latency-sensitive applications, such usage may still be more efficient than asking for a very large directory listing as it reduces the size of the payload passed between the Transfer service and the client.

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"])

List filtering to files modified before January 1, 2021. Note the use of an empty “start date” for the filter:

tc = globus_sdk.TransferClient(...)
for entry in tc.operation_ls(
    ep_id,
    path="/~/project1/",
    filter={"last_modified": ["", "2021-01-01"]},
):
    print(entry["name"], entry["type"])

GET /operation/endpoint/<endpoint_id>/ls

See List Directory Contents in the API documentation for details.

operation_mkdir(endpoint_id, path, *, local_user=None, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – The ID of the endpoint on which to create a directory

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

  • local_user (str | None) – Optional value passed to identity mapping specifying which local user account to map to. Only usable with Globus Connect Server v5 mapped collections.

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

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

POST /operation/endpoint/<endpoint_id>/mkdir

See Make Directory in the API documentation for details.

operation_rename(endpoint_id, oldpath, newpath, *, local_user=None, query_params=None)[source]#
Parameters:
  • endpoint_id (UUID | str) – 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

  • local_user (str | None) – Optional value passed to identity mapping specifying which local user account to map to. Only usable with Globus Connect Server v5 mapped collections.

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

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

POST /operation/endpoint/<endpoint_id>/rename

See Rename in the API documentation for details.

Parameters:
  • endpoint_id (UUID | str) – 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[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

Warning

This method is not currently supported by any collections.

get_submission_id(*, query_params=None)[source]#
Parameters:

query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

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 methods submit_transfer() and submit_delete() will call it automatically if the data does not contain a submission_id.

GET /submission_id

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

{
  "value": "00000000-0000-0000-34af-1252da510f05"
}
submit_transfer(data)[source]#
Parameters:

data (dict[str, Any] | TransferData) – A transfer task document listing files and directories, and setting various options. See TransferData for details

Return type:

GlobusHTTPResponse

Submit a Transfer Task.

If no submission_id is included in the payload, one will be requested and used automatically. The data passed to this method will be modified to include the submission_id.

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.

POST /transfer

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

submit_delete(data)[source]#
Parameters:

data (dict[str, Any] | DeleteData) – A delete task document listing files and directories, and setting various options. See DeleteData for details

Return type:

GlobusHTTPResponse

Submit a Delete Task.

If no submission_id is included in the payload, one will be requested and used automatically. The data passed to this method will be modified to include the submission_id.

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.

POST /delete

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

task_list(*, limit=None, offset=None, filter=None, query_params=None)[source]#

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

Parameters:
  • limit (int | None) – limit the number of results

  • offset (int | None) – offset used in paging

  • filter (str | Dict[str, str | List[str]] | None) – Only return task documents which match these filter clauses. For the filter syntax, see the External Documentation linked below. If a dict is supplied as the filter, it is formatted as a set of filter clauses. See filter formatting for details.

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

Fetch 10 tasks and print some basic info:

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

Fetch 3 specific tasks using a task_id filter:

tc = TransferClient(...)
task_ids = [
    "acb4b581-b3f3-403a-a42a-9da97aaa9961",
    "39447a3c-e002-401a-b95c-f48b69b4c60a",
    "02330d3a-987b-4abb-97ed-6a22f8fa365e",
]
for task in tc.task_list(filter={"task_id": task_ids}):
    print(
        f"Task({task['task_id']}): "
        f"{task['source_endpoint']} -> {task['destination_endpoint']}"
    )

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.

GET /task_list

See Task List in the API documentation for details.

task_event_list(task_id, *, limit=None, offset=None, query_params=None)[source]#

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

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

  • limit (int | None) – limit the number of results

  • offset (int | None) – offset used in paging

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

Fetch 10 events and print some basic info:

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

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.

GET /task/<task_id>/event_list

See Get Event List in the API documentation for details.

get_task(task_id, *, query_params=None)[source]#
Parameters:
  • task_id (UUID | str) – The ID of the task to inspect

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /task/<task_id>

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

update_task(task_id, data, *, query_params=None)[source]#

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 (UUID | str) – The ID of the task to modify

  • data (dict[str, Any]) – A partial task document with fields to update

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

PUT /task/<task_id>

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

cancel_task(task_id)[source]#

Cancel a task which is still running.

Parameters:

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

Return type:

GlobusHTTPResponse

POST /task/<task_id>/cancel

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

task_wait(task_id, *, timeout=10, polling_interval=10)[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 (UUID | str) – ID of the Task to wait on for completion

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

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

Return type:

bool

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(f"Another minute went by without {task_id} terminating")

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(f"{task_id} didn't successfully terminate!")
else:
    print(f"{task_id} completed")

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(f"\n{task_id} completed!")
task_pause_info(task_id, *, query_params=None)[source]#

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

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /task/<task_id>/pause_info

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

task_successful_transfers(task_id, *, marker=None, query_params=None)[source]#

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 (UUID | str) – The ID of the task to inspect

  • marker (str | None) – A marker for pagination

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

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(f"{info['source_path']} -> {info['destination_path']}")

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.

GET /task/<task_id>/successful_transfers

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

task_skipped_errors(task_id, *, marker=None, query_params=None)[source]#

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 (UUID | str) – The ID of the task to inspect

  • marker (str | None) – A marker for pagination

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

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(f"{info['error_code']} -> {info['source_path']}")

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.

GET /task/<task_id>/skipped_errors

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

endpoint_manager_monitored_endpoints(*, query_params=None)[source]#

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

Parameters:

query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

GET endpoint_manager/monitored_endpoints

See Get monitored endpoints and collections in the API documentation for details.

endpoint_manager_hosted_endpoint_list(endpoint_id, *, query_params=None)[source]#

Get shared endpoints hosted on the given endpoint.

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

GET /endpoint_manager/endpoint/<endpoint_id>/hosted_endpoint_list

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

endpoint_manager_get_endpoint(endpoint_id, *, query_params=None)[source]#

Get endpoint details as an admin.

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /endpoint_manager/endpoint/<endpoint_id>

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

endpoint_manager_acl_list(endpoint_id, *, query_params=None)[source]#

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

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

GET endpoint_manager/endpoint/<endpoint_id>/access_list

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

endpoint_manager_task_list(*, filter_status=None, filter_task_id=None, filter_owner_id=None, filter_endpoint=None, filter_endpoint_use=None, filter_is_paused=None, filter_completion_time=None, filter_min_faults=None, filter_local_user=None, last_key=None, query_params=None)[source]#

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 (None | str | Iterable[str]) – 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 (None | UUID | str | Iterable[UUID | str]) – 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 (UUID | str | None) – 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 (UUID | str | None) – Single endpoint id. Return only tasks with a matching source or destination endpoint or matching source or destination host endpoint.

  • filter_endpoint_use (Literal['source', 'destination'] | None) – In combination with filter_endpoint, filter to tasks where the endpoint or collection was used specifically as the source or destination of the transfer.

  • filter_is_paused (bool | None) – 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 (None | str | tuple[str | datetime, str | datetime]) – 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 | None) – 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 | None) – 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.

  • last_key (str | None) – the last key, for paging

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

Fetch some tasks and print some basic info:

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

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.

For example, fetch and print all active tasks visible via activity_monitor permissions:

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

GET endpoint_manager/task_list

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

endpoint_manager_get_task(task_id, *, query_params=None)[source]#

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

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /endpoint_manager/task/<task_id>

See Advanced Collection Management: Get task in the API documentation for details.

endpoint_manager_task_event_list(task_id, *, limit=None, offset=None, filter_is_error=None, query_params=None)[source]#

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 (UUID | str) – The ID of the task to inspect

  • limit (int | None) – limit the number of results

  • offset (int | None) – offset used in paging

  • filter_is_error (bool | None) – 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[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

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.

GET /task/<task_id>/event_list

See Advanced Collection Management: Get task events in the API documentation for details.

endpoint_manager_task_pause_info(task_id, *, query_params=None)[source]#

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 (UUID | str) – The ID of the task to inspect

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /endpoint_manager/task/<task_id>/pause_info

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

endpoint_manager_task_successful_transfers(task_id, *, marker=None, query_params=None)[source]#

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

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

  • marker (str | None) – A marker for pagination

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

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.

GET /endpoint_manager/task/<task_id>/successful_transfers

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

endpoint_manager_task_skipped_errors(task_id, *, marker=None, query_params=None)[source]#

Get skipped errors for a completed Task as an admin.

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

  • marker (str | None) – A marker for pagination

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

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

For more information, see how to make paginated calls.

GET /endpoint_manager/task/<task_id>/skipped_errors

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

endpoint_manager_cancel_tasks(task_ids, message, *, query_params=None)[source]#

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[UUID | str]) – List of task ids to cancel

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

POST /endpoint_manager/admin_cancel

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

endpoint_manager_cancel_status(admin_cancel_id, *, query_params=None)[source]#

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

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /endpoint_manager/admin_cancel/<admin_cancel_id>

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

endpoint_manager_pause_tasks(task_ids, message, *, query_params=None)[source]#

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[UUID | str]) – List of task ids to pause

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

POST /endpoint_manager/admin_pause

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

endpoint_manager_resume_tasks(task_ids, *, query_params=None)[source]#

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[UUID | str]) – List of task ids to resume

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

POST /endpoint_manager/admin_resume

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

endpoint_manager_pause_rule_list(*, filter_endpoint=None, query_params=None)[source]#

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

Parameters:
  • filter_endpoint (UUID | str | None) – 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[str, Any] | None) – Additional passthrough query parameters

Return type:

IterableTransferResponse

GET /endpoint_manager/pause_rule_list

See Get pause rules in the API documentation for details.

endpoint_manager_create_pause_rule(data)[source]#

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

Parameters:

data (dict[str, Any] | None) – A pause rule document describing the rule to create

Return type:

GlobusHTTPResponse

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"]

POST /endpoint_manager/pause_rule

See Create pause rule in the API documentation for details.

endpoint_manager_get_pause_rule(pause_rule_id, *, query_params=None)[source]#

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

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

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /endpoint_manager/pause_rule/<pause_rule_id>

See Get pause rule in the API documentation for details.

endpoint_manager_update_pause_rule(pause_rule_id, data)[source]#

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 (UUID | str) – The ID of the pause rule to update

  • data (dict[str, Any] | None) – A partial pause rule document with fields to update

Return type:

GlobusHTTPResponse

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)

PUT /endpoint_manager/pause_rule/<pause_rule_id>

See Update pause rule in the API documentation for details.

endpoint_manager_delete_pause_rule(pause_rule_id, *, query_params=None)[source]#

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 (UUID | str) – The ID of the pause rule to delete

  • query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

GlobusHTTPResponse

DELETE /endpoint_manager/pause_rule/<pause_rule_id>

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=None, source_endpoint=None, destination_endpoint=None, *, label=None, submission_id=None, sync_level=None, verify_checksum=False, preserve_timestamp=False, encrypt_data=False, deadline=None, skip_activation_check=None, skip_source_errors=False, fail_on_quota_errors=False, recursive_symlinks=None, delete_destination_extra=False, notify_on_succeeded=True, notify_on_failed=True, notify_on_inactive=True, source_local_user=None, destination_local_user=None, additional_fields=None)[source]#

Bases: 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 (globus_sdk.TransferClient | None) – 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 (UUIDLike | None) – The endpoint ID of the source endpoint

  • destination_endpoint (UUIDLike | None) – The endpoint ID of the destination endpoint

  • label (str | None) – A string label for the Task

  • submission_id (UUIDLike | None) – A submission ID value fetched via get_submission_id . Defaults to using transfer_client.get_submission_id

  • sync_level (_StrSyncLevel | int | None) – 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) – 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) – When true, Globus Transfer will attempt to set file timestamps on the destination to match those on the origin. [default: False]

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

  • deadline (datetime.datetime | str | None) – 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 | None) – 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_activation_check (bool | None) – When true, allow submission even if the endpoints aren’t currently activated

  • skip_source_errors (bool) – 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) – When true, quota exceeded errors will cause the task to fail. [default: False]

  • delete_destination_extra (bool) – 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]

  • notify_on_succeeded (bool) – Send a notification email when the transfer completes with a status of SUCCEEDED. [default: True]

  • notify_on_failed (bool) – Send a notification email when the transfer completes with a status of FAILED. [default: True]

  • notify_on_inactive (bool) – Send a notification email when the transfer changes status to INACTIVE. e.g. From credentials expiring. [default: True]

  • source_local_user (str | None) – Optional value passed to the source’s identity mapping specifying which local user account to map to. Only usable with Globus Connect Server v5 mapped collections.

  • destination_local_user (str | None) – Optional value passed to the destination’s identity mapping specifying which local user account to map to. Only usable with Globus Connect Server v5 mapped collections.

  • additional_fields (dict[str, t.Any] | None) – 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_filter_rule(name, *, method='exclude', type=None)[source]#

Add a filter rule to the transfer document.

These rules specify which items are or are not included when recursively transferring directories. Each item that is found during recursive directory traversal is matched against these rules in the order they are listed. The method of the first filter rule that matches an item is applied (either “include” or “exclude”), and filter rule matching stops. If no rules match, the item is included in the transfer. Notably, this makes “include” filter rules only useful when overriding more general “exclude” filter rules later in the list.

Parameters:
  • name (str) – A pattern to match against item names. Wildcards are supported, as are character groups: * matches everything, ? matches any single character, [] matches any single character within the brackets, and [!] matches any single character not within the brackets.

  • method (Literal['include', 'exclude']) – The method to use for filtering. If “exclude” (the default) items matching this rule will not be included in the transfer. If “include” items matching this rule will be included in the transfer.

  • type (None | Literal['file', 'dir']) – The types of items on which to apply this filter rule. Either "file" or "dir". If unspecified, the rule applies to both. Note that if a "dir" is excluded then all items within it will also be excluded regardless if they would have matched any include rules.

Example Usage:

>>> tdata = TransferData(...)
>>> tdata.add_filter_rule(method="exclude", "*.tgz", type="file")
>>> tdata.add_filter_rule(method="exclude", "*.tar.gz", type="file")

tdata now describes a transfer which will skip any gzipped tar files with the extensions .tgz or .tar.gz

>>> tdata = TransferData(...)
>>> tdata.add_filter_rule(method="include", "*.txt", type="file")
>>> tdata.add_filter_rule(method="exclude", "*", type="file")

tdata now describes a transfer which will only transfer files with the .txt extension.

add_item(source_path, destination_path, *, recursive=None, external_checksum=None, checksum_algorithm=None, additional_fields=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 destination directory or file will be transferred to

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

  • external_checksum (str | None) – 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 | None) – Specifies the checksum algorithm to be used when verify_checksum is True, sync_level is “checksum” or 3, or an external_checksum is given.

  • additional_fields (dict[str, Any] | None) – additional fields to be added to the transfer item

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

iter_items()[source]#

An iterator of items created by add_item.

Each item takes the form of a dictionary.

Return type:

Iterator[dict[str, Any]]

class globus_sdk.DeleteData(transfer_client=None, endpoint=None, *, label=None, submission_id=None, recursive=False, ignore_missing=False, interpret_globs=False, deadline=None, skip_activation_check=None, notify_on_succeeded=True, notify_on_failed=True, notify_on_inactive=True, local_user=None, additional_fields=None)[source]#

Bases: 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 (globus_sdk.TransferClient | None) – 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 (UUIDLike | None) – The endpoint ID which is targeted by this deletion Task

  • label (str | None) – A string label for the Task

  • submission_id (UUIDLike | None) – A submission ID value fetched via get_submission_id. Defaults to using transfer_client.get_submission_id if a transfer_client is provided

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

  • ignore_missing (bool) – Ignore nonexistent files and directories instead of treating them as errors. [default: False]

  • interpret_globs (bool) – Enable expansion of \*?[] characters in the last component of paths, unless they are escaped with a preceding backslash, \\ [default: False]

  • deadline (str | datetime.datetime | None) – 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

  • skip_activation_check (bool | None) – When true, allow submission even if the endpoint isn’t currently activated

  • notify_on_succeeded (bool) – Send a notification email when the delete task completes with a status of SUCCEEDED. [default: True]

  • notify_on_failed (bool) – Send a notification email when the delete task completes with a status of FAILED. [default: True]

  • notify_on_inactive (bool) – Send a notification email when the delete task changes status to INACTIVE. e.g. From credentials expiring. [default: True]

  • local_user (str | None) – Optional value passed to identity mapping specifying which local user account to map to. Only usable with Globus Connect Server v5 mapped collections.

  • additional_fields (dict[str, t.Any] | None) – 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, *, additional_fields=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.

Parameters:
  • path (str) – Path to the directory or file to be deleted

  • additional_fields (dict[str, Any] | None) – additional fields to be added to the delete item

iter_items()[source]#

An iterator of items created by add_item.

Each item takes the form of a dictionary.

Return type:

Iterator[dict[str, Any]]

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, *args, **kwargs)[source]#

Bases: GlobusAPIError

Error class for the Transfer API client.

Transfer Responses#

class globus_sdk.ActivationRequirementsResponse(*args, **kwargs)[source]#

Bases: 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, relative_time=True)[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).

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")
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)
>>> ...
class globus_sdk.IterableTransferResponse(response, client=None, *, iter_key=None)[source]#

Bases: 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"])