vhistsection module

This module contains a class VhistSection, which describes one workflow step of a VHIST document. Each workflow step has a list of attributes, which describe the workflow step. The following table lists all available attributes.

Attribute Name	Description
title	The title of the workflow step
description	A more elaborate description, which explains what the workflowstep does. Should not be longer then one or two sentences.
comment	An additional comment. Can for example be used to describe the reason why the workflow step has been executed.
command	The command used to execute the workflow step. By default, this attribute will be set to a jsonified version of sys.argv.
host	The hostname of the system, on which the workflow step has been executed. By default, this attribute is set to socket.gethostname().
user	The name of the user, which executed the workflow step. By default, this attribute is set to getpass.getuser().
tool	The name of the tool, which was executed during this workflow step. By default, this attribute is set to the version of python.
toolpath	The path to the tool, which was used to execute this workflow step. By default, it will be set to the path of the python executable as well as the path to python’s dist-packages site.
files	A list of files, which should be mentioned in or embedded into the workflow step. See also VhistFile for a description of embedded files.
previews	A list of previews for the workflow step. Can be visualizations of the input or output files, generated plots etc. See preview module for a detailed explanation of workflow step previews.
userAttrs	A dictionary containing key value pairs. This dictionary can store any additional information about the workflow step. The dictionary is an ordered dictionary and will therefore remember the order, in which you supplied additional user attributes. The workflow step will list the user attributes in this order in the generated VHIST file.

Each of these attributes are mapped to one python property with the same name. All properties are readable and writable. files, previews and userAttrs, however, do not allow you to replace their containers (lists and dictionaries), but the container objects can only be manipulated. This means that you can write

section.files.append(afile)
del section.previews[:] # clear the previews list
section.clear()

but not

section.files = []
section.previews = dict(numIteration = 30)

If you do not set a property’s value and the property has no default value, the property will not appear in the generated VHIST file.

The following snippet shows how to use the VhistSection class:

from pyeval.vhistsection import VhistSection

section = VhistSection(title="A workflow step",
        description="performs some work")
section.comment = "Results will be used in the presentation next week"
section.appendToVhistFile("output.vhist")

The default parameters for the attributes user, host, command, tool and toolpath can be retrieved with the following functions:

pyvhist.vhistsection.getUser(func)

getUser() Returns the name of the user, who executed this python script.

pyvhist.vhistsection.getHostname(func)

getHostname() Returns the name of the computer, on which this python script was executed.

pyvhist.vhistsection.getCommandline(func)

getCommandline() Returns a jsonified version of the commandline arguments in sys.argv.

pyvhist.vhistsection.getTool(func)

getTool() Returns the version of python used to run this script.

pyvhist.vhistsection.getToolpath(func)

getToolpath() Returns the path of the python executable as well as the path of the path of the dist-package site as a jsonified string.

class pyvhist.vhistsection.VhistSection(title=None, description=None, comment=None, command=getCommandline(), host=getHostname(), user=getUser(), tool=getTool(), toolpath=getToolpath(), debug=False, returnCommandline=False)

A class, which represents a section, you want to append to a VHIST file.

__init__(title=None, description=None, comment=None, command=getCommandline(), host=getHostname(), user=getUser(), tool=getTool(), toolpath=getToolpath(), debug=False, returnCommandline=False)

Creates a new VhistSection object. All parameters are optional and each parameter is associated with the equally named attribute described above.

createVhistSection(filename, rootFilename=None)

Adds the workflow step to the VHIST file named by filename. If rootFilename is None, a new VHIST file will be created. Otherwise, the file named by rootFilename will be copied to the location specified by filename and the workflow step is appended to the end of this file. If filename and rootFilename point to the same file, the section will be appended without copying. You can also specify a list of strings for filename. In this case, n equal VHIST files are created.

appendToVhistFile(vhistfile, additionalVhistfiles=())

Appends the workflow step to an existing VHIST file with the file path vhistfile. If the file does not exist, yet, a new VHIST file will be created.

Only for internal usage (such as unit testing) is the following method:

assembleCommandline(tempobj)

Returns a list of strings, which represents the commandline of vhistadd (without the executable). Preview images will be created at a temporary directory using the tempobj object.

tempobj must be of type TempDir. assembleCommandline uses it to create temporary files, such as previe images.