The saliweb.frontend Python module

class saliweb.frontend.CompletedJob(sql_dict)

A job that has completed. Use get_completed_job() to create such a job from a URL.

get_path(fname)

Get the full path to a file in the job’s directory.

Parameters:

fname (str) – The file name

Returns:

Full path to the file in the job’s directory.

get_results_available_time()

Get an HTML fragment stating how long results will be available

get_results_file_url(fname)

Return a URL which the user can use to download the passed file. The file must be in the job directory (or a subdirectory of it); absolute paths are not allowed. If files are compressed with gzip, the .gz extension can be ommitted here if desired. (If it is ommitted, the file will be automatically decompressed when the user downloads it; otherwise the original .gz file is downloaded.)

class saliweb.frontend.LoggedInUser(name, rd)

Information about the logged-in user. g.user is set to an instance of this class, or None if no user is logged in.

email = None

The contact email address of the user

first_name = None

The first name of the user

institution = None

The user’s institution

last_name = None

The last name of the user

modeller_key = None

The user’s MODELLER license key

name = None

The login name of the user

class saliweb.frontend.IncomingJob(given_name=None)

Represents a new job that is being submitted to the backend. Each new job has a unique name and a directory into which input files can be placed. Once all input files are in place, submit() should be called to submit the job to the backend.

Parameters:

given_name (str) – A user-provided name for the job.

directory = None

The directory on disk for this job. Input files should be placed in this directory prior to calling submit().

get_path(fname)

Get the full path to a file in the job’s directory.

Parameters:

fname (str) – The file name

Returns:

Full path to the file in the job’s directory.

name = None

The name of the job. Note that this is not necessarily the same as the name given by the user, since it must be unique, and fit in our database schema. (The user-provided name is thus sanitized if necessary and a unique suffix added.)

property results_url

The URL where this job’s results will be found when it is complete. This is only filled in when submit() is called.

submit(email=None, force_results_xml=False)

Submits the job to the backend to run on the cluster. If an email address is provided, it is notified when the job completes. If force_results_xml is True, force_xml=True is passed to the results URL, which can be used to force XML output even without the HTTP Accept header being set (used for backwards compatibility).

class saliweb.frontend.StillRunningJob(name, passwd, email, submit_time)

A job that is still running. See the still_running_template argument to get_completed_job().

email = None

Email address used to notify the user of job completion

get_refresh_time(minseconds)

Get a suitable time, in seconds, to wait to refresh the ‘job is still running’ page. It will be at least minseconds.

name = None

The name of the job

passwd = None

The password needed to access the job web pages

submit_time = None

The time (as a datetime.datetime object) when this job was submitted

class saliweb.frontend.Parameter(name, description, optional=False)

Represent a single parameter (with help). This is used to provide help to users of the REST API. See make_application().

Parameters:

• name (str) – The name (must match that of the form item).

• description (str) – Help text about the parameter and its use.

• optional (bool) – Whether the parameter can be omitted.

class saliweb.frontend.FileParameter(name, description, optional=False)

Represent a single file upload parameter (with help). See Parameter.

saliweb.frontend.make_application(name, parameters=[], static_folder='html', *args, **kwargs)

Make and return a new Flask application.

Parameters:

• name (str) – Name of the Python file that owns the app. This should normally be __name__.

• parameters (list) – The form parameters accepted by the ‘submit’ page. This should be a list of Parameter and/or FileParameter objects, and is used to provide help for users of the REST API.

Returns:

A new Flask application.

Note

Any additional arguments are passed to the Flask constructor.

saliweb.frontend.get_completed_job(name, passwd, still_running_template=None)

Create and return a new CompletedJob for a given URL. If the job is not valid (e.g. incorrect password) an exception is raised.

Parameters:

• name (str) – The name of the job.

• passwd (str) – Password for the job.

• still_running_template (str) – If given, the name of a Jinja2 template that will be used to report the ‘job is still running’ error; it is passed the error message as message and a StillRunningJob object as job.

Returns:

A new CompletedJob.

Return type:

CompletedJob

saliweb.frontend.get_db()

Get the MySQL database connection

saliweb.frontend.render_queue_page()

Return an HTML list of all jobs. Typically used in the /job route for a GET request.

saliweb.frontend.check_email(email, required=False)

Check a user-provided email address for sanity. If the address is invalid, raise an InputValidationError exception.

Parameters:

• email (str) – The email address to check.

• required (bool) – If True, an empty email address will also result in an exception (usually it is recommended that the email address is optional).

saliweb.frontend.check_modeller_key(modkey)

Check a provided MODELLER key. If the key is empty or invalid, raise an InputValidationError exception.

Parameters:

modkey (str) – The MODELLER key to check.

saliweb.frontend.check_pdb(filename, show_filename=None)

Check that a PDB file really looks like a PDB file. If it does not, raise an InputValidationError exception.

Parameters:

• filename (str) – The PDB file to check.

• show_filename (str) – If provided, include this filename in any error message to identify the PDB file (useful for services that allow upload of multiple PDB files).

saliweb.frontend.pdb_code_exists(code)

Return true iff the PDB code (e.g. 1abc) exists in our local copy of the PDB.

saliweb.frontend.get_pdb_code(code, outdir)

Look up the PDB code (e.g. 1abc) in our local copy of the PDB, and copy it into the given directory (usually an incoming job directory). The file will be named in standard PDB fashion, e.g. pdb1abc.ent. The full path to the file is returned. If the code is invalid or does not exist, raise an InputValidationError exception.

Parameters:

• code (str) – The PDB code to access (e.g. 1abc)

• outdir (str) – The directory to copy the PDB file into

Returns:

The full path to the new file in outdir

saliweb.frontend.get_pdb_chains(pdb_chain, outdir)

Similar to get_pdb_code(), find a PDB in our database, and make a new PDB containing just the requested one-letter chains (if any) in the given directory. The PDB code and the chains are separated by a colon. (If there is no colon, no chains, or the chains are just ‘-’, this does the same thing as get_pdb_code().) For example, ‘1xyz:AC’ would make a new PDB file containing just the A and C chains from the 1xyz PDB. The full path to the file is returned. If the code is invalid or does not exist, or at least one chain is specified that is not in the PDB file, raise an InputValidationError exception.

Parameters:

• pdb_chain (str) – PDB code and chain IDs, separated by a colon

• outdir (str) – Directory to write the PDB file into

Returns:

Full path to the new PDB file

saliweb.frontend.render_results_template(template_name, job, extra_xml_outputs=[], extra_xml_metadata={}, extra_xml_links={}, **context)

Render a template for the job results page. This normally functions like flask.render_template but will instead return XML if the user requests it (for the REST API). The XML file will include download links to any file mentioned in the template with CompletedJob.get_results_file_url(). Extra downloadable files can be added to the XML output by listing them in extra_xml_outputs. Custom tags can also be added to the XML output by listing them in extra_xml_metadata, which is a dict (keys are XML tag names, values are the XML values). extra_xml_links is similar except that the values are hyperlinks (xlink:href targets).

saliweb.frontend.render_submit_template(template_name, job, **context)

Render a template for the job submission page. This normally functions like flask.render_template but will instead return XML if the user requests it (for the REST API).

For very quick jobs that take only a few seconds to run, consider using redirect_to_results_page() instead.

saliweb.frontend.redirect_to_results_page(job)

Perform a redirect from the job-submission page to the job-results page. This normally functions like flask.redirect, but will instead return an XML document if the user requests it (for the REST API).

This can be used instead of render_submit_template() for a just-submitted job. (This is more appropriate for jobs that take only a few seconds to run.) The job results page should in turn call get_completed_job() with the still_running_template parameter to provide information on the job submission.

Parameters:

job (IncomingJob) – The just-submitted job.

exception saliweb.frontend.InputValidationError

Invalid user input, usually during a job submission. These errors are handled by reporting them to the user and asking them to fix their input accordingly.

exception saliweb.frontend.AccessDeniedError

Attempt by the user to access a protected page. These errors can be raised by any page and are generally handled by displaying an HTML/XML error page.