7.4. Python client#

This page contains the API reference of the functions in the vantage-client package.

7.4.1. User Client#

vantage6.client#

Client#: alias of UserClient

class UserClient(*args, log_level='debug', **kwargs)#

Bases: ClientBase

User interface to the vantage6-server

class Collaboration(parent)#

Bases: SubClient

Collection of collaboration requests

create(name, organizations, encrypted=False)#

Create new collaboration

Parameters:

name (str) – Name of the collaboration
organizations (list) – List of organization ids which participate in the collaboration
encrypted (bool, optional) – Whenever the collaboration should be encrypted or not, by default False

Returns:

Containing the new collaboration meta-data

Return type:

dict

get(id_)#

View specific collaboration

Parameters:: id (int) – Id from the collaboration you want to view
Returns:: Containing the collaboration information
Return type:: dict

list(scope='organization', name=None, encrypted=None, organization=None, page=1, per_page=20)#

View your collaborations

Parameters:

scope (str, optional) – Scope of the list, accepted values are organization and global. In case of organization you get the collaborations in which your organization participates. If you specify global you get the collaborations which you are allowed to see.
name (str, optional (with LIKE operator)) – Filter collaborations by name
organization (int, optional) – Filter collaborations by organization id
encrypted (bool, optional) – Filter collaborations by whether or not they are encrypted
page (int, optional) – Pagination page, by default 1
per_page (int, optional) – Number of items on a single page, by default 20

Returns:

Containing collabotation information

Return type:

list of dicts

Notes

Pagination does not work in combination with scope organization as pagination is missing at endpoint /organization/<id>/collaboration

class Node(parent)#

Bases: SubClient

Collection of node requests

create(collaboration, organization=None, name=None)#

Parameters:

collaboration (int) – Collaboration id to which this node belongs
organization (int, optional) – Organization id to which this node belongs. If no id provided the users organization is used. Default value is None
name (str, optional) – Name of the node. If no name is provided the server will generate one. Default value is None

Returns:

Containing the meta-data of the new node

Return type:

dict

delete(id_)#

Deletes a node

Parameters:: id (int) – Id of the node you want to delete
Returns:: Message from the server
Return type:: dict

get(id_)#

View specific node

Parameters:: id (int) – Id of the node you want to inspect
Returns:: Containing the node meta-data
Return type:: dict

kill_tasks(id_)#

Kill all tasks currently running on a node

Parameters:: id (int) – Id of the node of which you want to kill the tasks
Returns:: Message from the server
Return type:: dict

list(name=None, organization=None, collaboration=None, is_online=None, ip=None, last_seen_from=None, last_seen_till=None, page=1, per_page=20)#

List nodes

Parameters:

name (str, optional) – Filter by name (with LIKE operator)
organization (int, optional) – Filter by organization id
collaboration (int, optional) – Filter by collaboration id
is_online (bool, optional) – Filter on whether nodes are online or not
ip (str, optional) – Filter by node VPN IP address
last_seen_from (str, optional) – Filter if node has been online since date (format: yyyy-mm-dd)
last_seen_till (str, optional) – Filter if node has been online until date (format: yyyy-mm-dd)
page (int, optional) – Pagination page, by default 1
per_page (int, optional) – Number of items on a single page, by default 20

Return type:

list[dict]

Returns:

list of dicts – Containing meta-data of the nodes

update(id_, name=None, organization=None, collaboration=None)#

Update node information

Parameters:

id (int) – Id of the node you want to update
name (str, optional) – New node name, by default None
organization (int, optional) – Change the owning organization of the node, by default None
collaboration (int, optional) – Changes the collaboration to which the node belongs, by default None

Returns:

Containing the meta-data of the updated node

Return type:

dict

class Organization(parent)#

Bases: SubClient

Collection of organization requests

create(name, address1, address2, zipcode, country, domain, public_key=None)#

Create new organization

Parameters:

name (str) – Name of the organization
address1 (str) – Street and number
address2 (str) – City
zipcode (str) – Zip or postal code
country (str) – Country
domain (str) – Domain of the organization (e.g. vantage6.ai)
public_key (str, optional) – Public key of the organization. This can be set later, by default None

Returns:

Containing the information of the new organization

Return type:

dict

get(id_=None)#

View specific organization

Parameters:: id (int, optional) – Organization id of the organization you want to view. In case no id is provided it will display your own organization, default value is None.
Returns:: Containing the organization meta-data
Return type:: dict

list(name=None, country=None, collaboration=None, page=None, per_page=None)#

List organizations

Parameters:

name (str, optional) – Filter by name (with LIKE operator)
country (str, optional) – Filter by country
collaboration (int, optional) – Filter by collaboration id
page (int, optional) – Pagination page, by default 1
per_page (int, optional) – Number of items on a single page, by default 20

Returns:

Containing meta-data information of the organizations

Return type:

list[dict]

update(id_=None, name=None, address1=None, address2=None, zipcode=None, country=None, domain=None, public_key=None)#

Update organization information

Parameters:

id (int, optional) – Organization id, by default None
name (str, optional) – New organization name, by default None
address1 (str, optional) – Address line 1, by default None
address2 (str, optional) – Address line 2, by default None
zipcode (str, optional) – Zipcode, by default None
country (str, optional) – Country, by default None
domain (str, optional) – Domain of the organization (e.g. iknl.nl), by default None
public_key (str, optional) – public key, by default None

Returns:

The meta-data of the updated organization

Return type:

dict

class Result(parent)#

Bases: SubClient

Client to get the results of one or multiple algorithm runs

from_task(task_id)#

Get all results from a specific task

Parameters:: task_id (int) – Id of the task to get results from
Returns:: Containing the results
Return type:: list[dict]

get(id_)#

View a specific result

Parameters:: id (int) – id of the run you want to inspect
Returns:: Containing the run data
Return type:: dict

class Role(parent)#

Bases: SubClient

create(name, description, rules, organization=None)#

Parameters:

name (str) – Role name
description (str) – Human readable description of the role
rules (list) – Rules that this role contains
organization (int, optional) – Organization to which this role belongs. In case this is not provided the users organization is used. By default None

Returns:

Containing meta-data of the new role

Return type:

dict

delete(role)#

Delete role

Parameters:: role (int) – CAUTION! Id of the role to be deleted. If you remove roles that are attached to you, you might lose access!
Returns:: Message from the server
Return type:: dict

get(id_)#

View specific role

Parameters:: id (int) – Id of the role you want to insepct
Returns:: Containing meta-data of the role
Return type:: dict

list(name=None, description=None, organization=None, rule=None, user=None, include_root=None, page=1, per_page=20)#

List of roles

Parameters:

name (str, optional) – Filter by name (with LIKE operator)
description (str, optional) – Filter by description (with LIKE operator)
organization (int, optional) – Filter by organization id
rule (int, optional) – Only show roles that contain this rule id
user (int, optional) – Only show roles that belong to a particular user id
include_root (bool, optional) – Include roles that are not assigned to any particular organization
page (int, optional) – Pagination page, by default 1
per_page (int, optional) – Number of items on a single page, by default 20

Returns:

Containing roles meta-data

Return type:

list[dict]

update(role, name=None, description=None, rules=None)#

Update role

Parameters:

role (int) – Id of the role that updated
name (str, optional) – New name of the role, by default None
description (str, optional) – New description of the role, by default None
rules (list, optional) – CAUTION! This will not add rules but replace them. If you remove rules from your own role you lose access. By default None

Returns:

Containing the updated role data

Return type:

dict

class Rule(parent)#

Bases: SubClient

get(id_)#

View specific rule

Parameters:: id (int) – Id of the rule you want to view
Returns:: Containing the information about this rule
Return type:: dict

list(name=None, operation=None, scope=None, role=None, page=1, per_page=20)#

List of all available rules

Parameters:

name (str, optional) – Filter by rule name
operation (str, optional) – Filter by operation
scope (str, optional) – Filter by scope
role (int, optional) – Only show rules that belong to this role id
page (int, optional) – Pagination page, by default 1
per_page (int, optional) – Number of items on a single page, by default 20

Returns:

Containing all the rules from the vantage6 server

Return type:

list of dicts

class Run(parent)#

Bases: SubClient

from_task(task_id, include_task=False)#

Get all algorithm runs from a specific task

Parameters:

task_id (int) – Id of the task to get results from
include_task (bool, optional) – Whenever to include the task or not, by default False

Returns:

Containing the results

Return type:

list[dict]

get(id_, include_task=False)#

View a specific run

Parameters:

id (int) – id of the run you want to inspect
include_task (bool, optional) – Whenever to include the task or not, by default False

Returns:

Containing the run data

Return type:

dict

list(task=None, organization=None, state=None, node=None, include_task=False, started=None, assigned=None, finished=None, port=None, page=None, per_page=None)#

List runs

Parameters:

task (int, optional) – Filter by task id
organization (int, optional) – Filter by organization id
state (int, optional) – Filter by state: (‘open’,)
node (int, optional) – Filter by node id
include_task (bool, optional) – Whenever to include the task or not, by default False
started (tuple[str, str], optional) – Filter on a range of start times (format: yyyy-mm-dd)
assigned (tuple[str, str], optional) – Filter on a range of assign times (format: yyyy-mm-dd)
finished (tuple[str, str], optional) – Filter on a range of finished times (format: yyyy-mm-dd)
port (int, optional) – Port on which run was computed
page (int, optional) – Pagination page number, defaults to 1
per_page (int, optional) – Number of items per page, defaults to 20

Returns:

A dictionary containing the key ‘data’ which contains a list of runs, and a key ‘links’ which contains the pagination metadata.

Return type:

dict | list[dict]

class Task(parent)#

Bases: SubClient

create(collaboration, organizations, name, image, description, input_, databases=None)#

Create a new task

Parameters:

collaboration (int) – Id of the collaboration to which this task belongs
organizations (list) – Organization ids (within the collaboration) which need to execute this task
name (str) – Human readable name
image (str) – Docker image name which contains the algorithm
description (str) – Human readable description
input (dict) – Algorithm input
databases (list[dict], optional) – Databases to be used at the node. Each dict should contain at least a ‘label’ key. Additional keys are ‘query’ (if using SQL/SPARQL databases), ‘sheet_name’ (if using Excel databases), and ‘preprocessing’ information.

Returns:

A dictionairy containing data on the created task, or a message from the server if the task could not be created

Return type:

dict

delete(id_)#

Delete a task

Also removes the related runs.

Parameters:: id (int) – Id of the task to be removed
Returns:: Message from the server
Return type:: dict

get(id_, include_results=False)#

View specific task

Parameters:

id (int) – Id of the task you want to view
include_results (bool, optional) – Whenever to include the results or not, by default False

Returns:

Containing the task data

Return type:

dict

kill(id_)#

Kill a task running on one or more nodes

Note that this does not remove the task from the database, but merely halts its execution (and prevents it from being restarted).

Parameters:: id (int) – Id of the task to be killed
Returns:: Message from the server
Return type:: dict

list(initiating_org=None, initiating_user=None, collaboration=None, image=None, parent=None, job=None, name=None, include_results=False, description=None, database=None, run=None, status=None, user_created=None, page=1, per_page=20)#

List tasks

Parameters:

name (str, optional) – Filter by the name of the task. It will match with a Like operator. I.e. E% will search for task names that start with an ‘E’.
initiating_org (int, optional) – Filter by initiating organization
initiating_user (int, optional) – Filter by initiating user
collaboration (int, optional) – Filter by collaboration
image (str, optional) – Filter by Docker image name (with LIKE operator)
parent (int, optional) – Filter by parent task
job (int, optional) – Filter by job id
include_results (bool, optional) – Whenever to include the results in the tasks, by default False
description (str, optional) – Filter by description (with LIKE operator)
database (str, optional) – Filter by database (with LIKE operator)
run (int, optional) – Only show task that contains this run id
status (str, optional) – Filter by task status (e.g. ‘active’, ‘pending’, ‘completed’, ‘crashed’)
user_created (bool, optional) – If True, show only top-level tasks created by users. If False, show only subtasks created by algorithm containers.
page (int, optional) – Pagination page, by default 1
per_page (int, optional) – Number of items on a single page, by default 20

Returns:

dictonairy containing the key ‘data’ which contains the tasks and a key ‘links’ containing the pagination metadata

Return type:

dict

class User(parent)#

Bases: SubClient

create(username, firstname, lastname, password, email, organization=None, roles=[], rules=[])#

Create new user

Parameters:

username (str) – Used to login to the service. This can not be changed later.
firstname (str) – Firstname of the new user
lastname (str) – Lastname of the new user
password (str) – Password of the new user
email (str) – Email address of the new user
organization (int) – Organization id this user should belong to
roles (list of ints) – Role ids that are assigned to this user. Note that you can only assign roles if you own the rules within this role.
rules (list of ints) – Rule ids that are assigned to this user. Note that you can only assign rules that you own

Returns:

Containing data of the new user

Return type:

dict

get(id_=None)#

View user information

Parameters:: id (int, optional) – User id, by default None. When no id is provided your own user information is displayed
Returns:: Containing user information
Return type:: dict

list(username=None, organization=None, firstname=None, lastname=None, email=None, role=None, rule=None, last_seen_from=None, last_seen_till=None, page=1, per_page=20)#

List users

Parameters:

username (str, optional) – Filter by username (with LIKE operator)
organization (int, optional) – Filter by organization id
firstname (str, optional) – Filter by firstname (with LIKE operator)
lastname (str, optional) – Filter by lastname (with LIKE operator)
email (str, optional) – Filter by email (with LIKE operator)
role (int, optional) – Show only users that have this role id
rule (int, optional) – Show only users that have this rule id
last_seen_from (str, optional) – Filter users that have logged on since (format yyyy-mm-dd)
last_seen_till (str, optional) – Filter users that have logged on until (format yyyy-mm-dd)
page (int, optional) – Pagination page, by default 1
per_page (int, optional) – Number of items on a single page, by default 20

Returns:

Containing the meta-data of the users

Return type:

list of dicts

update(id_=None, firstname=None, lastname=None, organization=None, rules=None, roles=None, email=None)#

Update user details

In case you do not supply a user_id, your user is being updated.

Parameters:

id (int) – User id from the user you want to update
firstname (str) – Your first name
lastname (str) – Your last name
organization (int) – Organization id of the organization you want to be part of. This can only done by super-users.
rules (list of ints) – USE WITH CAUTION! Rule ids that should be assigned to this user. All previous assigned rules will be removed!
roles (list of ints) – USE WITH CAUTION! Role ids that should be assigned to this user. All previous assigned roles will be removed!
email (str) – New email from the user

Returns:

A dict containing the updated user data

Return type:

dict

class Util(parent)#

Bases: SubClient

Collection of general utilities

change_my_password(current_password, new_password)#

Change your own password by providing your current password

Parameters:

current_password (str) – Your current password
new_password (str) – Your new password

Returns:

Message from the server

Return type:

dict

generate_private_key(file_=None)#

Generate new private key

Parameters:: file (str, optional) – Path where to store the private key, by default None
Return type:: None

get_server_health()#

View the health of the vantage6-server

Returns:: Containing the server health information
Return type:: dict

get_server_version(attempts_on_timeout=None)#

View the version number of the vantage6-server :type attempts_on_timeout: Optional[int] :param attempts_on_timeout: Number of attempts to make when the server is not responding.

Default is unlimited.

Returns:: A dict containing the version number
Return type:: dict

reset_my_password(email=None, username=None)#

Start reset password procedure

Either a username of email needs to be provided.

Parameters:

email (str, optional) – Email address of your account, by default None
username (str, optional) – Username of your account, by default None

Returns:

Message from the server

Return type:

dict

reset_two_factor_auth(password, email=None, username=None)#

Start reset procedure for two-factor authentication

The password and either username of email must be provided.

Parameters:

password (str) – Password of your account
email (str, optional) – Email address of your account, by default None
username (str, optional) – Username of your account, by default None

Returns:

Message from the server

Return type:

dict

set_my_password(token, password)#

Set a new password using a recovery token

Token can be obtained through .reset_password(…)

Parameters:

token (str) – Token obtained from reset_password
password (str) – New password

Returns:

Message from the server

Return type:

dict

set_two_factor_auth(token)#

Setup two-factor authentication using a recovery token after you have lost access.

Token can be obtained through .reset_two_factor_auth(…)

Parameters:: token (str) – Token obtained from reset_two_factor_auth
Returns:: Message from the server
Return type:: dict

authenticate(username, password, mfa_code=None)#

Authenticate as a user

It also collects some additional info about your user.

Parameters:

username (str) – Username used to authenticate
password (str) – Password used to authenticate
mfa_token (str | int) – Six-digit two-factor authentication code

Return type:

None

wait_for_results(task_id, interval=1)#

Polls the server to check when results are ready, and returns the results when the task is completed.

Parameters:

task_id (int) – ID of the task that you are waiting for
interval (float) – Interval in seconds between checks if task is finished. Default 1.

Returns:

A dictionary with the results of the task, after it has completed.

Return type:

dict

vantage6.client.utils#

class LogLevel(value)#

Enum for the different log levels

Variables:

DEBUG (str) – The debug log level
INFO (str) – The info log level
WARN (str) – The warn log level
ERROR (str) – The error log level
CRITICAL (str) – The critical log level

7.4.2. Custom client exceptions#

vantage6.client.exceptions#

exception DeserializationException#: Exception raised when deserialization of algorithm input or result fails.