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.

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 /api/groups/{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

create_group(group_name)

Create a new group on AnVIL.

Calls the /api/groups/{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 /api/groups/{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 /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

get_billing_project(billing_project)

Get information about the specified billing project.

Calls the /api/billing/v2 GET method.

Parameters: billing_project (str) – Name of the billing project.
Returns: requests.Response

get_group(group_name)

Get information about a group on AnVIL.

Calls the /api/groups/{group_name} 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 /api/groups GET method.

Returns: requests.Response

get_proxy_group(email)

Get the proxy group created for a specific AnVIL account email.

Calls the /api/proxyGroup 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 /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 /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 /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 /me GET method.

Returns: requests.Response

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 /api/groups/{group_name}/{role}/{user_email} DELETE method.

Parameters

group_name (str) – Name of the group to remvoe 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

status()

Get the current AnVIL status.

Calls the /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 /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(method, 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 (e.g., “/api/get_groups”)
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). –

entry_point = 'https://api.firecloud.org/'

get(method, 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

method (str) – the API method to call (e.g., “/api/get_groups”)
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(method, 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 method to call (e.g., “/api/get_groups”)
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(method, 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 (e.g., “/api/get_groups”)
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(method, 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 method to call (e.g., “/api/get_groups”)
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). –