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, fields=None)

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: 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: AnVILAPIError

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

exception anvil_consortium_manager.anvil_api.AnVILAPIError404(response)

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

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

exception anvil_consortium_manager.anvil_api.AnVILAPIError500(response)

Bases: 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,), max_refresh_attempts=2, refresh_timeout=None, auth_request=None, default_host=None)

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