anvil_consortium_manager.anvil_api module

Python bindings for the AnVIL/Terra/Firecloud API

See API documentation for more information about each method: https://api.firecloud.org/#/.

class anvil_consortium_manager.anvil_api.AnVILAPIClient

Bases: object

Client for calling the AnVIL API.

See the AnVIL/Terra Swagger documentation for more info (https://api.firecloud.org/#/).

auth_session

An AnVILAPISession instance.

firecloud_entry_point

The entry point for the Firecloud API.

Type

str

rawls_entry_point

The entry point for the Rawls API.

Type

str

sam_entry_point

The entry point for the SAM API.

Type

str

add_user_to_group(group_name, role, user_email)

Add a user to a group on AnVIL. You must be an admin of the group to use this method.

Calls the Sam /api/groups/v1/{group_name}/{role}/{user_email} PUT method.

Parameters

  • group_name (str) – Name of the group to add this user to.

  • role (str) – Role that this user should have (either MEMBER or ADMIN).

  • user_email (str) – AnVIL email account of the user to add.

Returns

requests.Response

auth_session = None
clone_workspace(existing_workspace_namespace, existing_workspace_name, cloned_workspace_namespace, cloned_workspace_name, authorization_domains=[], copy_files_with_prefix=None)

Clone an existing workspace on AnVIL.

Calls the /api/create_workspace POST method.

Parameters

  • existing_workspace_namespace (str) – The namespace (or billing project) of the existing workspace to clone.

  • existing_workspace_name (str) – The name of the existing workspace to clone.

  • cloned_workspace_namespace (str) – The namespace (or billing project) in which to create the cloned workspace.

  • cloned_workspace_name (str) – The name of the cloned workspace to create.

  • authorization_domains (str) – If desired, a list of group names that should be used as the authorization domain for this workspace. This must include the authorization domains of the existing workspace.

Returns

requests.Response

create_group(group_name)

Create a new group on AnVIL.

Calls the Sam /api/groups/v1/{group_name} POST method.

Parameters

group_name (str) – Name of the AnVIL group to create.

Returns

requests.Response

create_workspace(workspace_namespace, workspace_name, authorization_domains=[])

Create a workspace on AnVIL.

Calls the /api/create_workspace POST method.

Parameters

  • workspace_namespace (str) – The namespace (or billing project) in which to create the workspace.

  • workspace_name (str) – The name of the workspace to create.

  • authorization_domains (str) – If desired, a list of group names that should be used as the authorization domain for this workspace.

Returns

requests.Response

delete_group(group_name)

Delete a group on AnVIL.

Calls the Sam /api/groups/v1/{group_name} DELETE method.

Parameters

group_name (str) – Name of the group to delete. You must be an admin of the group to use this method.

Returns

requests.Response

delete_workspace(workspace_namespace, workspace_name)

Delete a workspace on AnVIL. You must be an owner of the workspace to use this method.

Calls the Rawls /api/workspaces/{workspace_namespace}/{workspace_name} DELETE method.

Parameters

  • workspace_namespace (str) – The namespace (or billing project) of the workspace to be deleted.

  • workspace_name (str) – The name of the workspace to delete.

Returns

requests.Response

firecloud_entry_point = 'https://api.firecloud.org'
get_billing_project(billing_project)

Get information about the specified billing project.

Calls the Sam /api/billing/v2 GET method.

Parameters

billing_project (str) – Name of the billing project.

Returns

requests.Response

get_group_admins(group_name)

Get group admins on AnVIL.

Calls the Sam /api/groups/{group_name}/admin GET method.

Parameters

group_name (str) – Name of the AnVIL group to get information about.

Returns

requests.Response

get_group_email(group_name)

Get the email of a group on AnVIL.

Calls the Sam /api/groups/v1/{group_name} GET method.

Parameters

group_name (str) – Name of the AnVIL group whose email should be retrieved.

Returns

requests.Response

get_group_members(group_name)

Get group members on AnVIL.

Calls the Sam /api/groups/{group_name}/member GET method.

Parameters

group_name (str) – Name of the AnVIL group to get information about.

Returns

requests.Response

get_groups()

Get a list of groups that the authenticated account is part of.

Calls the Sam /api/groups GET method.

Returns

requests.Response

get_user(email)

Get the subject IDs associated with a specific AnVIL account email.

Calls the Sam /api/users/v1/{email} GET method.

Parameters

email (str) – Email address associated with the AnVIL account

Returns

requests.Response

get_workspace(workspace_namespace, workspace_name)

Get information about a specific workspace on AnVIL.

Calls the Rawls /api/workspaces/{workspace_namespace}/{workspace_name} GET method.

Parameters

  • workspace_namespace (str) – The namespace (or billing project) of the workspace.

  • workspace_name (str) – The name of the workspace.

Returns

requests.Response

get_workspace_acl(workspace_namespace, workspace_name)

Get the list of access controls for the workspace. This list includes both users and groups that have access. You must be an owner of this workspace to use this method.

Calls the Rawls /api/workspaces/{workspace_namespace}/{workspace_name}/acl GET method.

Parameters

  • workspace_namespace (str) – The namespace (or billing project) of the workspace.

  • workspace_name (str) – The name of the workspace.

Returns

requests.Response

list_workspaces(fields=None)

Get a list of workspaces that you have access to on AnVIL.

Calls the Rawls /api/workspaces GET method.

Parameters

  • fields (list) – List of strings indicating which fields to return. See API documentation

  • (https – //api.firecloud.org/#/Workspaces/getWorkspace) for more details.

Returns

requests.Response

me()

Get the current authenticated user.

Calls the Firecloud /me GET method.

Returns

requests.Response

rawls_entry_point = 'https://rawls.dsde-prod.broadinstitute.org'
remove_user_from_group(group_name, role, user_email)

Remove a user from a group on AnVIL. You must be an admin of the group to use this method.

Calls the Sam /api/groups/v1/{group_name}/{role}/{user_email} DELETE method.

Parameters

  • group_name (str) – Name of the group to remove this user from.

  • role (str) – Role that this user should be removed from (either MEMBER or ADMIN).

  • user_email (str) – AnVIL email account of the user to add.

Returns

requests.Response

sam_entry_point = 'https://sam.dsde-prod.broadinstitute.org'
status()

Get the current AnVIL status.

Calls the Firecloud /status GET method.

Returns

requests.Response

update_workspace_acl(workspace_namespace, workspace_name, acl_updates)

Update the access controls for a workspace for a set of users and/or groups. You must be an owner of the workspace to use this method.

Calls the Rawls /api/workspaces/{workspace_namespace}/{workspace_name} PATCH method.

Parameters

  • workspace_namespace (str) – The namespace (or billing project) of the workspace.

  • workspace_name (str) – The name of the workspace.

  • acl_updates (list of dict) – A list of dictionaries with access updates to make. Each dictionary should have the following keys: “email”, “accessLevel”, “canShare”, and “canCompute”.

Returns

requests.Response

exception anvil_consortium_manager.anvil_api.AnVILAPIError(response)

Bases: Exception

An exception raised when an error occurred with the AnVIL API.

status_code

the status code fo the response

Type

int

response

the response object.

Type

requests.Response

exception anvil_consortium_manager.anvil_api.AnVILAPIError400(response)

Bases: anvil_consortium_manager.anvil_api.AnVILAPIError

An exception raised when an 400 Bad Request code was returned by the AnVIL API.

exception anvil_consortium_manager.anvil_api.AnVILAPIError403(response)

Bases: anvil_consortium_manager.anvil_api.AnVILAPIError

An exception raised when an 403 Forbidden code was returned by the AnVIL API.

exception anvil_consortium_manager.anvil_api.AnVILAPIError404(response)

Bases: anvil_consortium_manager.anvil_api.AnVILAPIError

An exception raised when an 404 Not Found code was returned by the AnVIL API.

exception anvil_consortium_manager.anvil_api.AnVILAPIError409(response)

Bases: anvil_consortium_manager.anvil_api.AnVILAPIError

An exception raised when an 409 code was returned by the AnVIL API.

exception anvil_consortium_manager.anvil_api.AnVILAPIError500(response)

Bases: anvil_consortium_manager.anvil_api.AnVILAPIError

An exception raised when an 500 code was returned by the AnVIL API.

class anvil_consortium_manager.anvil_api.AnVILAPISession(credentials, refresh_status_codes=(<HTTPStatus.UNAUTHORIZED: 401>, ), max_refresh_attempts=2, refresh_timeout=None, auth_request=None, default_host=None)

Bases: google.auth.transport.requests.AuthorizedSession

An authorized session for use with the AnVIL API.

entry_point

The API entry point.

Type

str

delete(url, success_code=None, *args, **kwargs)

Make a delete request to the specified method after prepending entry_point.

Add the request and the response to the log.

If success_code is not None, check that the response code matches success_code. If they do not match, raise an AnVILAPIError exception (or one of its subclasses).

Parameters

  • method (str) – the API method to call

  • success_code (int, optional) – The

  • *args – Passed to AuthorizedSession.delete

  • **kwargs – Passed to AuthorizedSession.delete

Returns

requests.Response

Raises

  • AnVILAPIError – If the response code is not the expected success_code. May be a subclass based on the

  • response code (e.g., AnVILAPIError404). –

get(url, success_code=None, *args, **kwargs)

Make a get request to the specified method after prepending entry_point.

Add the request and the response to the log.

If success_code is not None, check that the response code matches success_code. If they do not match, raise an AnVILAPIError exception (or one of its subclasses).

Parameters

  • url (str) – the API url to call

  • success_code (int, optional) – The

  • *args – Passed to AuthorizedSession.get

  • **kwargs – Passed to AuthorizedSession.get

Returns

requests.Response

Raises

  • AnVILAPIError – If the response code is not the expected success_code. May be a subclass based on the

  • response code (e.g., AnVILAPIError404). –

patch(url, success_code=None, *args, **kwargs)

Make a patch request to the specified method after prepending entry_point.

Add the request and the response to the log.

If success_code is not None, check that the response code matches success_code. If they do not match, raise an AnVILAPIError exception (or one of its subclasses).

Parameters

  • method (str) – the API url to call

  • success_code (int, optional) – The

  • *args – Passed to AuthorizedSession.patch

  • **kwargs – Passed to AuthorizedSession.patch

Returns

requests.Response

Raises

  • AnVILAPIError – If the response code is not the expected success_code. May be a subclass based on the

  • response code (e.g., AnVILAPIError404). –

post(url, success_code=None, *args, **kwargs)

Make a post request to the specified method after prepending entry_point.

Add the request and the response to the log.

If success_code is not None, check that the response code matches success_code. If they do not match, raise an AnVILAPIError exception (or one of its subclasses).

Parameters

  • method (str) – the API method to call

  • success_code (int, optional) – The

  • *args – Passed to AuthorizedSession.post

  • **kwargs – Passed to AuthorizedSession.post

Returns

requests.Response

Raises

  • AnVILAPIError – If the response code is not the expected success_code. May be a subclass based on the

  • response code (e.g., AnVILAPIError404). –

put(url, success_code=None, *args, **kwargs)

Make a put request to the specified method after prepending entry_point.

If success_code is not None, check that the response code matches success_code. If they do not match, raise an AnVILAPIError exception (or one of its subclasses).

Parameters

  • method (str) – the API url to call

  • success_code (int, optional) – The

  • *args – Passed to AuthorizedSession.put

  • **kwargs – Passed to AuthorizedSession.put

Returns

requests.Response

Raises

  • AnVILAPIError – If the response code is not the expected success_code. May be a subclass based on the

  • response code (e.g., AnVILAPIError404). –