PyOptionTree Method Reference

__call__(self, name, default='__3YmqYOydQF', vardict={})

Identical to get().

__contains__(self, name)

Same as isValid(name)

__copy__(self)

Identical to copy().

__eq__(self, ot)

Tests the equality of two trees. Currently uses hashes, which is slower than directly, but this will hopefully change soon.

__init__(self, arg=None, userfunclist=[])

Initializes the option tree based on the type of arg. If arg is None or not given, it creates a new root node tree. If arg is another PyOptionTree, then it creates an identical copy of arg. If arg is a string, it assumes it is a filename and attempts to load the file name specified. If arg is a list, then it treats the list as a set of command line parameters (see addCommandLineArgs(...) for options; the lookforfiles parameter can be set by name here, e.g. lookforfiles=False)

userfunclist is a list of user defined functions which is passed to addUserFunctions() before any parsing is done. See help on addUserFunctions() for more information.

__len__(self)

Identical to size()

__str__(self)

Returns a string representation of the tree. The string can be passed back to the addString() method to reproduce the tree exactly, assuming any user-defined types that are stored in the tree can be pickled and unpickled properly.

All of the basic types and any functions not evaluated at parse time are turned into their string representations. Any types without a representation as a basic value are turned into a Python pickle using protocol=0, which can be manually edited. To make the file more readable, these are all put at the end of the file with links within the option tree pointing to them.

This string can be saved as a valid option tree file; reloading it produces an exact copy of the tree when saved, assuming any dependent files that are not loaded at parse time haven't changed (see the now() function to force evaluation at parse time).

Warning: If the given tree is not the root tree, any links pointing back to earlier nodes will be invalid.

addCommandLineArgs(self, arglist, lookforfiles=True)

Takes a list of parameters given on the command line, usually sys.argv[1:], and adds them, in order, to the option tree, overwriting any previous parameters by the same name. If lookforfiles is True (default), then option tree files may be specified with -f <filename> or --file=<filename>.

Command line options are given just like they are in files.

On the command line, specify the option file with -f <filename>. Multiple files can be specified; any options with the same name are overwritten by the last one specified. All the options within the files can be overwritten on the command line by specifying these as long options, i.e.:

MyOption = <value>

in the option file can be overwritten by:

--MyOption=<newvalue>

on the command line.

addOptionsFile(self, infile, sourcename='')

Opens and parses the file given by infile and all the parameters within it to the current option tree. If infile is a string, addOptionsFile attempts to open the file and parse the contents. If infile is a open file, it attempts to read the contents using readlines() and parse them. If infile is a list, it adds each file in order. All earlier definitions of a parameter are overwritten by later definitions, so be careful of adding multiple files. The list may be names, open files, or a mixture of both.

addString(self, s, sourcename='')

Adds options located in a string s. Optionally, the source may be provided with a sourcename used by the description() and fullName() methods and the error reporting functions.

addUserFunctions(self, userfunclist)

Adds a list of user defined functions that help with the parsing, overriding any previously specified with the same name. Each function will be passed the values given in the option tree (links will be followed and other functions will be evaluated). Whatever it returns will be stored in that option parameter.

Any exception propegates back up to the calling program.

userfunclist is a list of 2 or 3 element tuples. The first element is the name of the function (str) and the second is the function itself. Optionally, the third element may be True which signifies that the function should be evaluated when it's parsed instead of when the program requests it. An example list might be [('loadMyData', MyLoadFunction), ('loadmyDataNow', MyLoadFunction, True)].

Calling the function works just like in Python. If the function is called "foo", and the corresponding function is myFunc, then:

earlierparam = 343
myparam = foo('bar', 2, earlierparam)

in the parameter file will produce a call to myFunc with 'bar', 2, and 343 as the arguments and store the return value in myparam.

branchList(self)

Returns a list of the names of the branches of the local tree.

branches(self)

Returns a list of (<name>, <value>) tuples of all the branches in the tree.

copy(self)

Returns a copy of the tree. If the tree has a parent, the copy would share the same parent and name as the original, but all name resolutions from the original node ignore this one.

description(self)

Returns a description of the tree formed from the tree names and input sources on the path from the root to this node.

fetch(self, ot)

Imports all the keys and their corresponding retrieved values from the option tree ot into this tree.

fullTreeName(self)

Returne the name of the tree along with sources.

get(self, name, default='__3YmqYOydQF', vardict={}, recursionsleft=32)

Returns the parameter given by name. If default is given and the key is not found, or an error occurs retrieving the key, get() returns the default value instead of raising an exception.

vardict is an optional dictionary of variables and/or functions that are used in addition to globals() when evaluating any of the Python code.

name is in the same format as links, namely tree1/subtree/parameter. Referencing from the root of the tree when get() is called from a subtree is possible with a '/' prefix, and moving from a subtree to a parent tree is possible using '..'.

isValid(self, name, vardict={})

Returns True if name exists and is valid (no errors) and False otherwise.

itemList(self)

Returns a list of the names of all the items in the local tree.

items(self)

Returns a list of (<name>, <value>) tuples of all the parameters and branches in the local tree.

leafList(self)

Returns a list of the names of all the parameters in the tree, excluding branches.

leaves(self)

Returns a list of (<name>, <value>) tuples of all the parameters in the tree, excluding branches.

nameFromRoot(self)

Returns the full name of the tree, referenced from the root.

parent(self)

Returns the parent of the tree, or None if it's the root.

pathFromRoot(self)

Returns the list of tree names from the root of the tree to this one, starting with '/'.

printTree(self)

Prints the string representation of the tree to stdout. See the reference for __str__() for info about the format of the string.

root(self)

Returns the root tree.

saveTree(self, filename)

Saves the tree to an option tree file given by filename that can be reloaded and used. Note that any existing file by the name of filename will be overwritten.

saveTreeAsLog(self, fileprefix, filesuffix='opt')

Saves the tree to an option tree file that can be reloaded and used. The name of the file is given by fileprefix-<timestamp>.filesuffix, and is thus useful for logging purposes. The time stamp is in the format year-month-day-hour-min-sec, for example 2007-07-29-22-32-00, which indicates 10:32 pm on July 29, 2007.

Note that the results of a test could be put into the tree using the set() method and then saved as part of the log file.

set(self, name, value)

Manually sets the value of an option. Returns a reference to the option tree.

size(self)

Returns the number of variables and branches in this node of the tree.

strhash(self)

Returns a string hash of alphanumeric characters of the option tree. The current implementation is a little slow, as it retrieves all the values, thus it is immune to links and the like.

string(self, includeheader=False)

This is the same as __str__(), but it allows some extra options.

treeName(self)

Returns the name of the tree.

update(self, udict)

This function updates the current option tree with all the key, value pairs in udict. The keys can be anything in link format, and the value pairs can be any type.