8.2.2. vantage6.client.UserClient#

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

Bases: ClientBase

User interface to the vantage6-server

__init__(*args, log_level='info', **kwargs)#

Create user client

All paramters from ClientBase can be used here.

Parameters:

log_level (str, optional) – The log level to use, by default ‘info’

Methods

__init__(*args[, log_level])

Create user client

authenticate(username, password[, mfa_code])

Authenticate as a user

generate_path_to(endpoint, ...)

Generate URL to endpoint using host, port and endpoint

refresh_token()

Refresh an expired token using the refresh token

request(endpoint[, json, method, params, ...])

Create http(s) request to the vantage6 server

setup_collaboration(collaboration_id)

Setup the collaboration.

setup_encryption(private_key_file)

Enable the encryption module fot the communication

wait_for_results(task_id[, interval])

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

Attributes

base_path

Full path to the server URL.

headers

Defines headers that are sent with each request.

host

Host including protocol (HTTP/HTTPS)

name

Return the node's/client's name

path

Path/endpoint at the server where the api resides

port

Port on which vantage6 server listens

token

JWT Authorization token

class Collaboration(parent)#

Bases: SubClient

Collection of collaboration requests

add_organization(organization, collaboration=None)#

Add an organization to a collaboration

Parameters:
  • organization (int) – Id of the organization you want to add to the collaboration

  • collaboration (int, optional) – Id of the collaboration you want to add the organization to. If no id is provided the value of setup_collaboration() is used.

Returns:

Containing the updated list of organizations in the collaboration

Return type:

list[dict]

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

delete(id_=None, delete_dependents=None)#

Deletes a collaboration

Parameters:
  • id (int) – Id of the collaboration you want to delete

  • delete_dependents (bool, optional) – Delete the tasks, nodes and studies that are part of the collaboration as well. If this is False, and dependents exist, the server will refuse to delete the collaboration. Default is False.

Returns:

Message from the server

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, algorithm_store=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

  • algorithm_store (int, optional) – Filter collaborations by algorithm store id that is available for the collaboration

  • 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[dict]

Notes

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

remove_organization(organization, collaboration=None)#

Remove an organization from a collaboration

Parameters:
  • organization (int) – Id of the organization you want to remove from the collaboration

  • collaboration (int, optional) – Id of the collaboration you want to remove the organization from. If no id is provided the value of setup_collaboration() is used.

Returns:

Containing the updated list of organizations in the collaboration

Return type:

list[dict]

update(id_=None, name=None, encrypted=None, organizations=None)#

Update collaboration information

Parameters:
  • id (int) – Id of the collaboration you want to update. If no id is provided the value of setup_collaboration() is used.

  • name (str, optional) – New name of the collaboration

  • encrypted (bool, optional) – New encryption status of the collaboration

  • organizations (list[int], optional) – New list of organization ids which participate in the collaboration

Returns:

Containing the updated collaboration information

Return type:

dict

class Node(parent)#

Bases: SubClient

Collection of node requests

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

Register new node

Parameters:
  • collaboration (int) – Collaboration id to which this node belongs. If no ID was provided the, collaboration from client.setup_collaboration() is used.

  • 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, study=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. If no id is provided but collaboration was defined earlier by user, filtering on that collaboration

  • study (int, optional) – Filter by study 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, clear_ip=None)#

Update node information

Parameters:
  • id (int) – Id of the node you want to update

  • name (str, optional) – New node name, by default None

  • clear_ip (bool, optional) – Clear the VPN IP address of the node, 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, study=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. If client.setup_collaboration() was called, the previously setup collaboration is used. Default value is None

  • study (int, optional) – Filter by study 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)#

Register new role

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 SubClient(parent)#

Bases: object

Create sub groups of commands using this SubClient

Parameters:

parent (UserClient | AlgorithmClient) – The parent client

class Task(parent)#

Bases: SubClient

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

Create a new task

Parameters:
  • 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

  • collaboration (int, optional) – Id of the collaboration to which this task belongs. Should be set if the study is not set

  • study (int, optional) – Id of the study to which this task belongs. Should be set if the collaboration is not set

  • 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, study=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. If no id is provided but collaboration was defined earlier by setup_collaboration(), filtering on that collaboration

  • study (int, optional) – Filter by study

  • 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_code (str | int) – Six-digit two-factor authentication code

Return type:

None

property base_path: str#

Full path to the server URL. Combination of host, port and api-path

Returns:

Server URL

Return type:

str

generate_path_to(endpoint, is_for_algorithm_store)#

Generate URL to endpoint using host, port and endpoint

Parameters:
  • endpoint (str) – endpoint to which a fullpath needs to be generated

  • is_for_algorithm_store (bool) – Whether the request is for the algorithm store or not

Returns:

URL to the endpoint

Return type:

str

property headers: dict#

Defines headers that are sent with each request. This includes the authorization token.

Returns:

Headers

Return type:

dict

property host: str#

Host including protocol (HTTP/HTTPS)

Returns:

Host address of the vantage6 server

Return type:

str

property name: str#

Return the node’s/client’s name

Returns:

Name of the user or node

Return type:

str

property path: str#

Path/endpoint at the server where the api resides

Returns:

Path to the api

Return type:

str

property port: int#

Port on which vantage6 server listens

Returns:

Port number

Return type:

int

refresh_token()#

Refresh an expired token using the refresh token

Raises:
  • Exception – Authentication Error!

  • AssertionError – Refresh URL not found

Return type:

None

request(endpoint, json=None, method='get', params=None, headers=None, first_try=True, retry=True, attempts_on_timeout=None, is_for_algorithm_store=False)#

Create http(s) request to the vantage6 server

Parameters:
  • endpoint (str) – Endpoint of the server

  • json (dict, optional) – payload, by default None

  • method (str, optional) – Http verb, by default ‘get’

  • params (dict, optional) – URL parameters, by default None

  • headers (dict, optional) – Additional headers to be sent with the request, by default None

  • first_try (bool, optional) – Whether this is the first attempt of this request. Default True.

  • retry (bool, optional) – Try request again after refreshing the token. Default True.

  • attempts_on_timeout (int, optional) – Number of attempts to make when a timeout occurs. Default None which leads to unlimited amount of attempts.

  • is_for_algorithm_store (bool, optional) – Whether the request is for the algorithm store. Default False.

Returns:

Response of the server

Return type:

dict

setup_collaboration(collaboration_id)#

Setup the collaboration.

This gets the collaboration from the server and stores its details in the client and sets the algorithm stores available for this collaboration. When this has been called, other functions no longer require the collaboration_id to be provided.

Parameters:

collaboration_id (int) – Id of the collaboration

Return type:

None

setup_encryption(private_key_file)#

Enable the encryption module fot the communication

This will attach a Crypter object to the client. It will also verify that the public key at the server matches the local private key. In case they differ, the local public key is uploaded to the server.

Parameters:

private_key_file (str) – File path of the private key file

Raises:

AssertionError – If the client is not authenticated

Return type:

None

property token: str#

JWT Authorization token

Returns:

JWT token

Return type:

str

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