scitools.configdata

The Python module ConfigParser supports configuration files with the usual Windows .INI file syntax. The present configdata module extends the syntax of configuration files and provides a more easy-to-use interface to such files. Variables can also be defined on the command-line and through environment variables in addition to the configuration file.

User-friendly reading of configuration files with an extended Windows .INI syntax.

The configuration file has sections in square brackets (e.g., [modes]) and option=value assignments in each section. The extended syntax offers type specification of the options. After the = sign the type appears in <> brackets followed by the value, e.g.:

[my section]
my first option = <bool> off   # can be on, off, yes, no, 1, 0
my second option = <float> 3.2
my third option = <eval> [1, 4, 'tmp.ps']  # a list as option value
my fourth option = MyClass     # no type specification here
my fifth option = <eval> StringFunction('sin(x)*cos(x)')

The type must be bool, int, float, str, or eval. As an example, the ‘my second option’ value will be a Python float object with the value 3.2 (without this type facility, the value would be the string “3.2”). In case of eval, the value is processed as eval(value) such that values can become lists, dictionaries, or other user-defined objects. In the latter case, the globals_ keyword must be set explicitly so that this function has access to the user’s classes (eval(value, globals_)). For example, ‘my fifth option’ will evaluate to StringFunction object, but this requires supply of globals_ with the user’s imported modules (from StringFunction and math).

There is also a syntax for marking options to be read-only, i.e., these options are meant to be set in configuration files and not changed later in the program. Preceeding the type specification by an r or R indicates the read-only property, e.g.:

my first option = r<bool> off

Options set in the configuration file can be overridden by associated environment variables whose names are on the form:

prefix_section_option

For example, an option ‘DEBUG’ in section ‘globals’ can have an associated environment variable MYPACK_globals_DEBUG, if the prefix is MYPACK. The prefix is set in a special section called ‘modes’ (see below).

Options can also be overridden by command-line arguments. The command-line options have the same names as the associated environment variable names, but additionally prefixed by a double hyphen, e.g. –MYPACK_globals_DEBUG. The ‘command line arguments’ option in the ‘modes’ section must have a true value for this functionality to be active.

Here is an example of the ‘modes’ section:

[modes]
envir prefix = MATHPACK
command line arguments = yes

If section or option names contain space(s), the corresponding environment variable name and command-line option have the space(s) replaced by underscore(s), e.g.:

MATHPACK_my_section_my_first_option
--MATHPACK_my_section_my_first_option

Such command-line options and values are removed from sys.argv after being read.

A convenient feature of configuration files is that variable interpolation is possible(see the documentation of ConfigParser in the Python Library Reference). Here is an example:

[DEFAULT]
path = /my/home/dir/

[storage]
datapath = %(path)s/data
input = %(path)s/%(datapath)s/input

One can also provide variables for being used in variable interpolation throught the default_dict4intpl argument to this function.

A configuration file is searched for and read in as follows (in the listed order):

1. basename.cfg in the default_file_location directory,

2. basename.cfg files for each directory in other_locations list, 4. .basename.cfg in the user’s home directory, 3. .basename.cfg in the directory where the main script is running.

This priority implies that the a config file in the current working directory will override any user or any other system settings.

scitools.configdata.tobool(value)

Convert value (1, ‘1’, 0, ‘0’, ‘yes’, ‘true’, ‘no’, ‘false’, ‘on’, ‘off’, or any integer) to a bool object. The string values are treated in a case-insensitive way.

scitools.configdata.config_parser_frontend(basename, default_file_location, extension='.cfg', other_locations=[], default_dict4intpl={}, globals_=None)

User-friendly reading of configuration files with an extended Windows .INI syntax.

The configuration file has sections in square brackets (e.g., [modes]) and option=value assignments in each section. The extended syntax offers type specification of the options. After the = sign the type appears in <> brackets followed by the value, e.g.:

[my section]
my first option = <bool> off   # can be on, off, yes, no, 1, 0
my second option = <float> 3.2
my third option = <eval> [1, 4, 'tmp.ps']  # a list as option value
my fourth option = MyClass     # no type specification here
my fifth option = <eval> StringFunction('sin(x)*cos(x)')

The type must be bool, int, float, str, or eval. As an example, the ‘my second option’ value will be a Python float object with the value 3.2 (without this type facility, the value would be the string “3.2”). In case of eval, the value is processed as eval(value) such that values can become lists, dictionaries, or other user-defined objects. In the latter case, the globals_ keyword must be set explicitly so that this function has access to the user’s classes (eval(value, globals_)). For example, ‘my fifth option’ will evaluate to StringFunction object, but this requires supply of globals_ with the user’s imported modules (from StringFunction and math).

There is also a syntax for marking options to be read-only, i.e., these options are meant to be set in configuration files and not changed later in the program. Preceeding the type specification by an r or R indicates the read-only property, e.g.:

my first option = r<bool> off

Options set in the configuration file can be overridden by associated environment variables whose names are on the form:

prefix_section_option

For example, an option ‘DEBUG’ in section ‘globals’ can have an associated environment variable MYPACK_globals_DEBUG, if the prefix is MYPACK. The prefix is set in a special section called ‘modes’ (see below).

Options can also be overridden by command-line arguments. The command-line options have the same names as the associated environment variable names, but additionally prefixed by a double hyphen, e.g. –MYPACK_globals_DEBUG. The ‘command line arguments’ option in the ‘modes’ section must have a true value for this functionality to be active.

Here is an example of the ‘modes’ section:

[modes]
envir prefix = MATHPACK
command line arguments = yes

If section or option names contain space(s), the corresponding environment variable name and command-line option have the space(s) replaced by underscore(s), e.g.:

MATHPACK_my_section_my_first_option
--MATHPACK_my_section_my_first_option

Such command-line options and values are removed from sys.argv after being read.

A convenient feature of configuration files is that variable interpolation is possible(see the documentation of ConfigParser in the Python Library Reference). Here is an example:

[DEFAULT]
path = /my/home/dir/

[storage]
datapath = %(path)s/data
input = %(path)s/%(datapath)s/input

One can also provide variables for being used in variable interpolation throught the default_dict4intpl argument to this function.

A configuration file is searched for and read in as follows (in the listed order):

1. basename.cfg in the default_file_location directory,

2. basename.cfg files for each directory in other_locations list, 4. .basename.cfg in the user’s home directory, 3. .basename.cfg in the directory where the main script is running.

This priority implies that the a config file in the current working directory will override any user or any other system settings.

scitools.configdata.values_only(data)

Strip the three-tuple (value, str2type, readonly) in the dictionary returned from config_parser_frontend to a dictionary with option values only.

scitools.configdata.dict2xml(data, syntax='gnosis', section_name='section', option_name='option')

Takes a data dictionary, as output from the config_parser_frontend function, and stores in a string with XML syntax.

@param data: dictionary of the form data[section][option] = (v, s2t, ro), where v is a Python object (value), s2t is a callable, and ro is a bool. @param syntax: ‘gnosis’ gives gnosis XML_Pickler syntax, ‘plain’ gives a simpler to read syntax. @param section_name: the name of sections (highest key level) in the data dictionary to be used as XML tagname. (“section” and “option” are the terms used by the Python ConfigParser tool.) @param option_name: the name of options (lowest key level) in the data dictionary to be used as XML tagname. @return: a string with XML syntax.