userattrs module

Each VHIST workflow step and workflow file allow you to add arbitrary user-defined attributes in the form of key-value pairs. The classes in this module allow you to easily specify them and reuse their definitions within your code. This way, you do not have to specify each attribute twice, such as:

from pyvhist.vhistfile import InFile

# create constants used in your code
IMAGE_WIDTH = 200
IMAGE_HEIGHT = 150
IMAGE_DEPTH = 32
IMAGE_SEGMENTS = 5

# add each constant to the vhist workflow file
vfile = InFile("image.png")
vfile.userAttrs["imageWidth"] = IMAGE_WIDTH
vfile.userAttrs["imageHeight"] = IMAGE_HEIGHT
vfile.userAttrs["imageDepth"] = IMAGE_DEPTH
vfile.userAttrs["imageSegments"] = IMAGE_SEGMENTS

# use the constants in your code
for i in range(IMAGE_WIDTH):
    for j in range(IMAGE_HEIGHT):
        image[i,j] += 10

Instead, you can create an object of type UserAttributes, add all parameters to this class and then include the user attributes with one call into a vhist workflow step or file:

from pyvhist.userattrs import UserAttributes
from pyvhist.vhistfile import InFile

# create constants used in your code
P = UserAttributes()
P.imageWidth = 200
P.imageHeight = 150
P.imageDepth = 32
P.imageSegments = 5

# add all constants at once to the workflow file
vfile = InFile("image.png")
P.addToUserAttrs(vfile)

# use P in your code
for i in range(P.imageWidth):
    for j in range(P.imageHeight):
        image[i,j] += 10

Each user-defined attribute can have a unit. For example, if you deal with lengths, you want to document if the lenghts are in mm, inches, pixels or light-years. You can document the unit of a user-defined attribute with the help of the UserValue class:

from pyvhist.userattrs import UserAttributes, UserValue
P = UserAttributes()
P.imageWidth = UserValue(200, unit="pixels")
P.imageHeight = UserValue(150, unit="pixels")
P.imageDepth = UserValue(32, unit="bits")

While units are important when documenting attributes, they are not used in code very often. Therefore, UserAttributes automatically detects if you assign a UserValue object to it. When you access this property, only the value stored in the UserValue object is returned:

P = UserAttributes()
P.imageWidth = UserValue(200, unit="pixels")

print P.imageWidth # returns only the value 200

User Value also provides a keyword option formatStr in the constructor. This option can be used to define how number-like objects are displayed within the VHIST file:

P = UserAttributes()
P.radius = UserValue(10, unit="mm")
P.circumference = UserValue(2 * math.pi * P.radius, unit="mm",
        formatStr=":class:`.3f`")

class pyvhist.userattrs.UserValue(value, unit=None, formatStr=None, verbatim=False)

A class, which can store a value, an associated unit and a format string.

__init__(value, unit=None, formatStr=None, verbatim=False)

Creates a UserValue object.

unit is a string, which specifies the unit associated with the value.

formatStr is a string, which is used to format numeric values.

class pyvhist.userattrs.UserAttributes

A class, which stores key-value pairs.

__init__()

Create a UserAttributes object.

addToUserAttrs(secOrFile, prefix='')

Adds the user-defined attributes stored in the UserAttributes object to the VhistSection or VhistFile object given by secOrFile.

prefix is an optional parameter. If prefix is set to a non-empty string, all parameters will be prefixed with the prefix followed by a ‘.’.