cerise_client package

Submodules

cerise_client.errors module

exception cerise_client.errors.CommunicationError

Bases: Exception

There was an error communicating with the service.

exception cerise_client.errors.FileNotFound

Bases: Exception

The file you tried to set as a workflow input was not found. Is the path correct? Does the file exist?

exception cerise_client.errors.InvalidJob

Bases: Exception

You submitted an invalid job. Did you forget to add a workflow?

exception cerise_client.errors.JobAlreadyExists

Bases: Exception

You tried to create a job with a name that already existed on this service. Jobs must have a unique name, and cannot be submitted twice.

exception cerise_client.errors.JobNotFound

Bases: Exception

The given job does not exist on this service. Either it never existed because it hasn’t been submitted yet (did you call job.run()?), or it was deleted.

exception cerise_client.errors.MissingOutput

Bases: Exception

The output returned by the service does not refer to an existing file. Maybe the job was deleted?

exception cerise_client.errors.NoPrimaryFile

Bases: Exception

You tried to set a secondary file for an input for which no primary file is set. Use add_input_file() first, then add_secondary_file() with the same input name.

exception cerise_client.errors.PortNotAvailable

Bases: Exception

The requested port is occupied by another service, or by some other program that has bound it on localhost. Either stop the blocking service or program, or try again with a different port number.

exception cerise_client.errors.ServiceAlreadyExists

Bases: Exception

A service with the given name already exists on this machine, so another one cannot be created.

exception cerise_client.errors.ServiceNotFound

Bases: Exception

The given service does not exist on this machine. Either it was never created, or it was destroyed, or the Docker container running it was destroyed by an outside influence.

exception cerise_client.errors.UnknownInput

Bases: Exception

You tried to set the value for an input that is not in the workflow for the job you are creating. Did you add the workflow first?

cerise_client.job module

class cerise_client.job.Job(service, name, job_id=None, inputs=None, workflow=None, input_desc=None)

Bases: object

Create a new Job object.

This will not actually make a job on the service. Use Service.create_job() to make a job.

Parameters:

• service (Service) – The service this job will run on.
• name (str) – The name for the job.

add_input_file(input_name, file_path)

Adds an input file for the given workflow input.

The set_workflow() function must be called before this one. The input name must correspond to an input defined in the workflow. The file’s name must not equal that of any other file added using this function or add_secondary_file(), or that of the workflow itself.

If this function is called repeatedly with the same input name, the last file will be used.

Note that this function will upload the input file to the service for this job. If the file is large and/or the connection slow, then this will take a while.

Parameters:

• input_name (str) – The name of a workflow input.
• file_path (str) – The path to the input file to use.

Raises:

• UnknownInput – The input name does not match any in this workflow, or the workflow was not yet set.
• FileNotFound – The file to be used was not found.

add_secondary_file(input_name, file_path)

Adds a secondary file for the given workflow input.

A primary file must be set using add_input_file() first.

The input name must correspond to an input defined in the workflow. The file’s name must not equal that of any other file added using this function or add_secondary_file(), or that of the workflow itself.

Note that this function will upload the input file to the service for this job. If the file is large and/or the connection slow, then this will take a while.

Parameters:

• input_name (str) – The name of a workflow input.
• file_path (str) – The path to the input file to use.

Raises:

• UnknownInput – The input name does not match any in this workflow, or the workflow was not yet set.
• FileNotFound – The file to be used was not found.
• NoPrimaryFile – No primary file was set yet via add_input_file().

cancel()

Cancel this job; stop it running at the compute service. After this function is called, the job’s state will eventually become ‘Cancelled’, unless it was already complete, in which case its state will be its normal final state.

id = None

str – The service-assigned id of this job.

is_running()

Returns True when the job is still running, False when it is done.

Returns:Whether the job is running. Return type:boolean

log

str – The job’s log, as produced by the service.

name = None

str – The name of this job.

outputs

Returns a dictionary of output objects. Keys are taken from the names of the outputs in the submitted workflows, the values are the corresponding results.

If an output is of type File, an object of class OutputFile is returned as the value.

If no outputs are available, returns None.

Returns:Output values or None. Return type:Union[dict, None]

run()

Starts the job running on the associated service.

Returns:The id given to this job by the service. Return type:str

set_input(input_name, value)

Sets the value of a workflow input.

Use this function for setting the value of numerical or string inputs. For File inputs, use add_input_file.

Parameters:

• input_name (str) – The name of a workflow input.
• value (Union[str,int,double]) – The value to set.

Raises:

UnknownInput – The input name does not match any in this workflow, or the workflow was not yet set.

set_workflow(file_path)

Sets the workflow file.

Only one workflow file may be submitted; if this function is called repeatedly, the last workflow file is used.

Parameters:file_path (str) – The path to the CWL file defining the workflow to be run. The file’s name must not equal that of any file added using add_input_file(). Raises:FileNotFound – The workflow file was not found at the given path.

state

The state that this job is in.

None if the job has not been started yet. One of ‘Waiting’, ‘Running’, ‘Success’, ‘Cancelled’, ‘TemporaryFailure’, ‘PermanentFailure’, or ‘SystemError’.

cerise_client.output_file module

class cerise_client.output_file.OutputFile(uri)

Bases: object

Creates a new OutputFile object.

Parameters:uri (str) – The URI at which the file is available.

content

Returns the file in binary form.

Returns:The contents of the file as raw bytes. Return type:bytes

save_as(file_path)

Downloads the file and saves it to disk.

Parameters:

file_path (str) – The path to save the file to.

Raises:

• IOError – There was a problem saving the file.
• errors.MissingOutput – The output doesn’t exist. Maybe the job was deleted?

text

Returns the file in text form.

Autodetects the encoding and converts to a standard Python unicode str.

Returns:The contents of the file as text. Return type:str Raises:errors.MissingOutput – The output doesn’t exist. Maybe the job was deleted?

cerise_client.service module

class cerise_client.service.Service(name, port)

Bases: object

Create a new Service object.

Note that this does not actually create the Docker container; use create_service(), get_service() or service_from_dict() to obtain a Service object with an actual corresponding service.

Parameters:

• name (str) – The name for the service (and its corresponding Docker container).
• port (int) – The port number on which the service runs.

create_job(job_name)

Creates a job to run on the given service.

Parameters:job_name (str) – The name of the job. This must be unique among all jobs on this service, and must consist of letters, digits, underscores and hyphens. A GUID or similar is recommended. Returns:The new job. Return type:Job Raises:JobAlreadyExists – A job with this name already exists on this service.

destroy_job(job)

Removes a job, including all its input and output data, from the service.

Parameters:

job (Job) – The job to be removed.

Raises:

• JobNotFound – No job with this name or id was found on this service. Did you destroy it twice?
• CommunicationError – There was an error communicating with the service.

get_job_by_id(job_id)

Gets a job by its id.

Parameters:job_id (str) – The id of the job, as returned by job.id after it’s been created. Returns:The requested job. Return type:Job Raises:JobNotFound – The job is unknown to this service. Either it was deleted, or it never existed on this service.

get_job_by_name(job_name)

Gets a job by its name. Only jobs that have been submitted are on the service, so if job.run() has not been called, this will not find the job.

Parameters:job_name (str) – The name of the job, as set when it was created. Returns:The requested job. Return type:Job Raises:JobNotFound – The job is unknown to this service. Either it was deleted, or it never existed. Did you run() the job?

get_log()

Get the internal Cerise log for this service. If things are not working as you expect them to (e.g. a job status of SystemError), the log may contain useful information on what went wrong.

Returns:The job log Return type:str

list_jobs()

List all the jobs known to the service. Note that only jobs that have been submitted are known to the service, if you have not called job.run() yet, it won’t be in there.

Returns:A list of known jobs. Return type:[Job] Raises:CommunicationError – There was a problem communicating with the service. Is it running?

cerise_client.service.create_managed_service(srv_name, port, srv_type, user_name=None, password=None)

Creates a new managed service for a given user at a given port.

Parameters:

• srv_name (str) – A unique name for the service. Must be a valid Docker container name.
• port (int) – A unique port number on which the service will be made available. It will listen only on localhost.
• srv_type (str) – The type of service to launch. This is the name of the Docker image to use.
• user_name (str) – The user name to use to connect to the compute resource.
• password (str) – The password to use to connect to the compute resource.

Returns:

The created service

Return type:

Service

Raises:

• ServiceAlreadyExists – A service with this name already exists.
• PortNotAvailable – The requested port is occupied.

cerise_client.service.destroy_managed_service(srv)

Destroys a managed service.

This will make the service unavailable, and delete all jobs and information about them (including input and output data) in this service and on the compute resource.

Parameters:srv (Service) – A managed service. Raises:ServiceNotFound – A service with this name was not found.

cerise_client.service.get_managed_service(srv_name, port)

Gets a managed service by name and port.

Parameters:

• srv_name (str) – Name that the service was created with. Must be a valid Docker container name.
• port (int) – Port number that the service was created with.

Returns:

The service, if it exists.

Return type:

Service

Raises:

ServiceNotFound – The requested service does not exist.

cerise_client.service.managed_service_exists(srv_name)

Checks whether a managed service with the given name exists.

Parameters:srv_name (str) – Name of the service. Must be a valid Docker container name. Returns:True iff the service exists Return type:bool

cerise_client.service.managed_service_is_running(srv)

Checks whether the managed service is running.

Returns:True iff the service is running. Return type:bool

cerise_client.service.require_managed_service(srv_name, port, srv_type, user_name=None, password=None)

Creates a new managed service for a given user at a given port, if it does not already exist.

If a service with the given name already exists, it is returned instead and no new service is created.

Parameters:

• srv_name (str) – A unique name for the service. Must be a valid Docker container name.
• port (int) – A unique port number on which the service will be made available. It will listen only on localhost.
• srv_type (str) – The type of service to launch. This is the name of the Docker image to use.
• user_name (str) – The user name to use to connect to the compute resource.
• password (str) – The password to use to connect to the compute resource.

Returns:

The created service

Return type:

Service

Raises:

PortNotAvailable – The requested port is occupied.

cerise_client.service.service_from_dict(srv_dict)

Gets a service from a dictionary.

The dictionary must have been created by a call to service_to_dict().

Parameters:srv_dict (dict) – A dictionary describing the service. Returns:The service, if it exists. Return type:Service Raises:ServiceNotFound – The requested service does not exist.

cerise_client.service.service_to_dict(srv)

Saves the service to a dictionary.

The dictionary can later be used to recreate the Service object by passing it to service_from_dict(). The exact format of the dictionary is not given, but it contains only Python built-in types so that it can easily be stored or otherwise serialised.

Returns:

A dictionary with information necessary to rebuild

the Service object.

Return type:dict

cerise_client.service.start_managed_service(srv)

Start a stopped managed service.

Does nothing if the service is already running.

cerise_client.service.stop_managed_service(srv)

Stop a running managed service.

This must be done before shutting down the computer, to ensure a clean shutdown. Does nothing if the service is already stopped.

Module contents