config – Pebl’s configuration system

The config module defines a set of parameter types and functions to validate user input. A module or class can define a parameter by creating an instance of one of the Parameter classes – it is automatically registered with the config module. Many modules provide a fromconfig() factory function that create and return a parametrized object.

Specifying Parameters

A Parameter definition requires the following:

• a name of the form section.option (examples: data.filename, result.format)

• a short description

• a validator function

  The function has one argument: the string value of the parameter. It should return true if the value is valid and false otherwise. The config module includes several factory functions that create validator functions. See section on validator factories.

• a default value specified as a string

Example parameter definitions

From the pebl.data module:

_pfilename = config.StringParameter(
    'data.filename',
    'File to read data from.',
    config.fileexists(),
)

In the above example, the config.fileexists() function returns a validator function that checks whether the file exists.

From the pebl.result module:

_psize = config.IntParameter(
    'result.numnetworks',
    \"\"\"Number of top-scoring networks to save. Specify 0 to indicate that
    all scored networks should be saved.\"\"\",
    default=1000
)

In the above example, The IntParameter subclass of Parameter automatically checks whether the parameter value is an integer and raises an error if it is not. It thus does not require an additional validator.

Parameter Types

class pebl.config.StringParameter(name, description, validator=<function default_validator>, default=None)

class pebl.config.IntParameter(name, description, validator=<function default_validator>, default=None)

class pebl.config.FloatParameter(name, description, validator=<function default_validator>, default=None)

Validator Factories

The following functions create validator functions.

pebl.config.between(min, max)

Returns validator that checks whether value is between min and max.

pebl.config.oneof(*values)

Returns validator that checks whether value is in approved list.

pebl.config.atleast(min)

Returns validator that checks whether value is > min.

pebl.config.atmost(max)

Returns validator that checks whether value is < max.

pebl.config.fileexists()

Returns validator that checks whether value is an existing file.

Using Parameters

Parameters can be set with the config.set function or in a configuration file. The config file should be in a format compatible with Python’s ConfigParser module.

Specifying parameter values using a config file:

[data]
filename = example_data.txt

[result]
format=html

Specifying parameter values using config.set:

from pebl import config
config.set('data.filename', 'example_data.txt')
config.set('result.format', 'html')

pebl.config.set(name, value, source='config.set')

Set a parameter value.

• name should be of the form “section.name”.
• value can be a string which will be casted to the required datatype.
• source specifies where this parameter value was specified (config file, command line, interactive shell, etc).

The following functions are used for reading, getting, writing and listing parameters.

pebl.config.read(filename)

Reads parameter from config file.

Config files should conform to the format specified in the ConfigParser module from Python’s standard library. A Parameter’s name has two parts: the section and the option name. These correspond to ‘section’ and ‘option’ as defined in ConfigParser.

For example, parameter ‘foo.bar’ would be specified in the config file as:

[foo]
bar = 5

pebl.config.get(name)

Returns value of parameter.

Raises KeyError if parameter not found. Examples:

from pebl import config
config.get('data.filename')
config.get('result.format')

The value returned could be the default value or the latest value set using config.set or config.read

pebl.config.write(filename, include_defaults=False)

Writes parameters to config file.

If include_default is True, writes all parameters. Else, only writes parameters that were specifically set (via config file, command line, etc).

pebl.config.parameters(section=None)

Returns list of parameters.

If section is specified, returns parameters for that section only. section can be a section name or a search string to use with string.startswith(..)

pebl.config.configobj(params)

Given a list of parameters, returns a ConfigParser object.

This function can be used to convert a list of parameters to a config object which can then be written to file.