playmolecule.session module

class playmolecule.session.Session(token=None, wait_for_backend=False, server_ip=None, server_port=None, server_version='v1', server_protocol='http')

Bases: object

The central class through which we control the PlayMolecule backend.

Starts a PlayMolecule session with a user token, each user has his own unique token. There are some operations which can only be performed by using the Admin token.

Parameters

  • token (str) – The user token. If None it will try to read it from the config file.

  • wait_for_backend (bool) – If set to True, it will block execution until it manages to contact the PlayMolecule backend

  • server_ip (str) – The IP address of the backend server. If None it will try to read it from the config file.

  • server_port (int) – The port on which the backend server listens. If None it will try to read it from the config file.

  • server_version (str) – The API version of the backend server. If None it will try to read it from the config file.

  • server_protocol (str) – The protocol used by the backend server.

Examples

>>> s = Session("my_token")
>>> s = Session("my_token", server_ip="127.0.0.1", server_port=8095, wait_for_backend=True)
cancel_job(execid, _logger=True)

Cancels a job.

This will set the status to ERROR and stop any running execution (children as well)

Parameters

execid (str) – The execution ID of the job we wish to cancel

change_password(email, old_pass, new_pass, admin_token=None)

Change the password of a user

Parameters

  • email (str) – The email address of the user

  • old_pass (str) – The old password of the user

  • new_pass (str) – The new password for the user

  • admin_token (str) – The admin user token. If None you are only able to modify the current user’s password.

delete_job(execid, _logger=True)

Deletes a job and all associated data and metadata related to it from the backend. Cannot be undone.

Parameters

  • execid (str) – The execution ID of the job we wish to cancel

  • _logger (bool) – If set to False it reduces the verbosity of the output

describe_app(appname, version=None, _logger=True)

Describe the input parameters of an app.

Parameters

  • appname (str) – The app name

  • version (str) – The app version to be described.

  • _logger (bool) – Set to False to return the app information as a dictionary. Otherwise it will be printed to sys.stdout.

get_apps(_logger=True)

Returns or prints the available apps.

The list of apps is printed if _logger is True else it’s returned

Parameters

_logger (bool) – Set as True for printing the info and errors in sys.stdout. If False, it returns the same information as an object.

Returns

app_list – A list with all the app info

Return type

list

get_job(execid=None, name=None, group=None, strict=True, _logger=True)

Finds and returns a Job object

Parameters

  • execid (str) – The execution id

  • name (str) – The name of an execution

  • group (str) – The group of an execution

  • strict (bool) – If strict is True, Job creation will raise exceptions if not able to load correctly the app configuration into the Job.

  • _logger (bool) – If False, it will reduce verbosity.

Returns

job – The job object with all it’s parameters set

Return type

Job

Examples

>>> job = s.get_job(execid="3cadd50b-b208-4a3d-8cf3-d991d22e858a")
get_jobs(limit=None, group=None, appid=None, execid=None, count=False, in_status=None, not_in_status=None, newer_than=None, older_than=None, _logger=True)

Returns or prints a list of submitted jobs.

Parameters

  • limit (int) – Maximum number of jobs to be listed or returned

  • group (str) – The executions group to be returned

  • appid (str) – Specify the id of an app to return only executions of this app

  • execid (str) – Specify the execution ID of a job. It can accept a partial beginning of an execution ID or the whole execid

  • count (bool) – If True it will only return the number of jobs matching the above criteria

  • in_status (list) – A list of JobStatus codes. Jobs which are in any of the specified states will be returned

  • not_in_status (list) – A list of JobStatus codes. Only jobs which don’t belong to any of the specified states will be returned

  • newer_than (int) – Return only jobs more recent than newer_than seconds.

  • older_than (int) – Return only jobs more old than older_than seconds.

  • _logger (bool) – Set as True for printing the info and errors in sys.stdout. If False, it returns the same information as a list (default=True).

Returns

execs – A list of job executions

Return type

list

get_service_status(_logger=True)

Gets the current status of all PlayMolecule backend services

Parameters

_logger (bool) – Set to False to return the status of the services instead of printing them to sys.stdout

login()

Logs in a user retrieving the user token from the user name and password

register(admin_token)

Registers a new user in the backend

Parameters

admin_token (str) – The admin user token

retrieve_jobs(outdir='.', force=False, execid=None, name=None, group=None, recursive=False, _logger=True)

Retrieve the results of several jobs.

Parameters

  • outdir (str) – Path to which to retrieve the jobs

  • force (bool) – If force=True, the destination folder will be overwritten

  • execid – The id of the job to be retrieved.

  • name (str) – The name of an execution to be retrieved

  • group (str) – The group of an execution to be retrieved

  • recursive (bool) – Set to True to store the jobs in subfolders named by the job names

  • _logger (bool) – Set to False to reduce verbosity

Examples

>>> s.retrieve_jobs("./results", execid="3cadd50b-b208-4a3d-8cf3-d991d22e858a")
>>> s.retrieve_jobs("./results", group="my_job_group") # Will retrieve all jobs of the group
set_job_status(execid, status, error_info=None, _logger=True)

Sets the status of a job

Parameters

  • execid (str) – The execution ID of the job to modify

  • status (JobStatus) – The status to which to set the job

  • error_info (str) – If the status is Error you can provide verbose information on the error for the users

  • _logger (bool) – Set to False to reduce verbosity

Examples

>>> s.set_job_status(execid="3cadd50b-b208-4a3d-8cf3-d991d22e858a", status=JobStatus.ERROR)
start_app(appname, version=None, _logger=True)

Returns a new job object of the specified app.

Parameters

  • appname (str) – The app name of the used app.

  • version (str) – The app version to be used.

  • _logger (bool) – Set as True for printing the info and errors in sys.stdout. If False, it returns the same information as an object (default=True).

Returns

job – The new job object

Return type

Job

Examples

>>> job = s.start_app("ProteinPrepare")
>>> job.pdbid = "3ptb"
>>> job.submit()
wait_for_backend()

Blocks execution until it’s able to contact the backend server

exception playmolecule.session.SessionError

Bases: Exception

exception playmolecule.session.UserFailedRegistrationError

Bases: Exception

exception playmolecule.session.UserNotFoundError

Bases: Exception

exception playmolecule.session.UserUpdateError

Bases: Exception