playmolecule.job module

class playmolecule.job.Job(session, appid, execid=None, job_json=None, strict=True)

Bases: protocolinterface.protocolinterface.ProtocolInterface

Create a Job object given the user session and an app id.

Parameters

  • session (Session) – The user session

  • appid (str) – The app ID

  • execid (str) – The ID of the job if it has already been submited

  • job_json (dict) – A dictionary from which to instantiate the job. Useful when creating a job from data from the API

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

cancel(_logger=True)

Cancel the job

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

describe(_logger=True)

Describes the input parameters of an application

Parameters

_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

app_descr – The description of the inputs of an app

Return type

list

get_children(status=None, return_dict=False, _logger=True)

Returns the children of the job.

Parameters

  • status (list of JobStatus) – Only get children with specific job statuses given in a list

  • return_dict (bool) – Set to True to return a dictionary with the children information instead of Job objects

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

Returns

children – The children of the job

Return type

list

get_error_info(_logger=True)

Get information related to an errored job

Parameters

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

Returns

error_info – Information on the cause of the error

Return type

str

get_progress(_logger=True)

Prints the job progress.

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 (default=True).

Returns

  • info (str) – The information on the current progress

  • completion (str) – The completion percentage

get_status(_logger=True)

Prints or returns the job status

Parameters

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

Returns

status – The current status of the job

Return type

JobStatus

read_arguments(filename, ftype='yaml')

Reads argument values of the job from a json or yaml file

Parameters

  • filename (str) – The name of the file (incl. extension) from which to read the arguments

  • ftype (str) – Can be either “json” or “yaml” depending on what file format you want to read

retrieve(path=None, force=False, skip=False, on_status=(<JobStatus.RUNNING: 3>, <JobStatus.COMPLETED: 4>, <JobStatus.ERROR: 5>, <JobStatus.SLEEPING: 7>), attempts=5, execid_subdir=True, tmpdir=None, _logger=True)

Retrieve the results of a job execution.

The output will be retrieved in the working directory if the argument path is not passed, inside a folder with the id job as a name. If this folder already exists, another one with a timestamp will be created. If the job has not completed, the function will try to download intermediate results.

Parameters

  • path (str) – Destination folder

  • force (bool) – If the destination folder exists and force == True, the destination folder will be removed.

  • skip (bool) – If the destination folder exists and skip == True, nothing will be performed.

  • on_status (list or JobStatus) – Restrict at which job status the results will be retrieved

  • attempts (int) – How many times to attempt downloading the data from minio

  • execid_subdir (bool) – If True it will create a subdirectory inside path with the execution ID as name and retrieve the results there

  • tmpdir (str) – Set a different directory for storing temporary files. If set to None it defaults to /tmp/

  • _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

path – The destination path of the retrieved data

Return type

str

Examples

>>> job.retrieve("./results/", on_status=(JobStatus.COMPLETED, JobStatus.ERROR))
submit(child_of=None, queue_config=None, _logger=True)

Submits the job to the PlayMolecule backend server.

Parameters

  • child_of (str) – The id of another job. If provided, the new job will be submited as a child of that job.

  • queue_config (dict) – A dictionary containing key-value pairs for defailed configuration for this job on the queueing system. You can specify “cpus”, “memory” and “priority” for the job.

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

Examples

>>> job = sess.start_app("proteinprepare")
>>> job.pdbid = "3ptb"
>>> job.submit(queue_config={"ncpu": 2, "memory": 4000, "priority": 500})
wait(on_status=(<JobStatus.COMPLETED: 4>, <JobStatus.ERROR: 5>), seconds=10, _logger=True, _return_dataset=True)

Blocks execution until the job has reached the specific status or any of a list of statuses.

Parameters

  • on_status (JobStatus or list of JobStatus) – The status(es) at which the job will not be waited upon and the code execution will continue.

  • seconds (float) – The sleep time between status cheching

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

wait_children(on_status=(<JobStatus.COMPLETED: 4>, <JobStatus.ERROR: 5>), seconds=10, _logger=True)

Blocks execution until all the children of the job have reached the given status

Parameters

  • on_status (JobStatus or list of JobStatus) – The status(es) at which a child job will stop being waited upon

  • seconds (float) – The sleep time between status checking of the children jobs

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

write_arguments(filename, ftype='yaml')

Writes the current argument values of the job to a json or yaml file

Parameters

  • filename (str) – The name of the file (incl. extension) in which to write the arguments

  • ftype (str) – Can be either “json” or “yaml” depending on what file format you want to write

exception playmolecule.job.JobBucketNotFoundError

Bases: Exception

exception playmolecule.job.JobConfigNotLoadedError

Bases: Exception

exception playmolecule.job.JobError

Bases: Exception

class playmolecule.job.JobStatus(value)

Bases: enum.IntEnum

Job status codes describing the current status of a job

WAITING_DATA : Waiting for communication fromm the job. Job has not reached the queue yet for computation. VALIDATING : Job is pending validation by admins WAITING_APPROVAL : Job is pending approval by admins RUNNING : Job is currently running COMPLETED : Job has successfully completed ERROR : Job has exited with an error QUEUED : Job is queued for execution SLEEPING : Job is sleeping and will be respawned soon. Used by periodically executing apps.

COMPLETED = 4
ERROR = 5
QUEUED = 6
RUNNING = 3
SLEEPING = 7
VALIDATING = 1
WAITING_APPROVAL = 2
WAITING_DATA = 0
describe()
class playmolecule.job.StringOrDataset

Bases: protocolinterface.validators._Validator

validate(value)
playmolecule.job.short_execid(execid)

Returns the short execution ID of a job from the full execution ID