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)	Use private key file to setup encryption of sensitive data.
`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=False)#

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.

Return type:

None

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)#

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
Return type:: None

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

delete(id_, delete_dependents=False)#

Deletes an organization

Parameters:

id (int) – Id of the organization you want to delete.
delete_dependents (bool, optional) – Delete the nodes, users, runs, tasks and roles that are part of the organization as well. If this is False, and dependents exist, the server will refuse to delete the organization. Default is False.

Return type:

None

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)#

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!
Return type:: None

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, store=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
store (int, optional) – ID of the algorithm store to retrieve the algorithm from
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
Return type:: None

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, store=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
store (int, optional) – Filter by algorithm store from which the algorithm was retrieved
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

delete(id_)#

Delete user

Parameters:: id (int) – Id of the user you want to delete
Return type:: None

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)#

Use private key file to setup encryption of sensitive data.

This function will use the private key file to setup encryption and decryption of task input and results. It needs to be called once per client in encrypted collaborations to ensure that the client can read and write encrypted data.

A Cryptor object that handles encryption and decryption will be attached to the client, after verifying that the public key at the server matches the provided private key. In case the server’s public key does not match with the local public key, the local one is uploaded to the server.

Parameters:: private_key_file (str | None) – File path of the private key file, or None if encryption is not enabled
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