The config_parser module

New tools for parsing configuration files.

Classes

ConfigParser

class src.tools.config_parser.ConfigParser(filePath, fileFormat, substitutions=None, defaultValues=None, preserveCase=True)

A class to parse configuration files in a variety of ways.

Parameters :

filePath : string

The absolute path to the configuration file.

fileFormat : int

The flag indicating the format of the configuration file. Options are the following:

FORMAT_BASIC

The file is treated as a standard configuration file. All return values are strings, unless one of the specialized accessor methods is used.

FORMAT_REPR

The file consists of entries formatted according to __repr__, so that they can be cast back to the appropriate types using __eval__.

FORMAT_AUTO

The parser attempts to guess the format of the entries based on syntax.

substitutions : dict

A dictionary whose keys are strings. The values will be substituted into the file wherever the corresponding key is referenced (using the standard rules for string formatting).

defaultValues : dict

A dictionaries whose keys are tuples of strings. The first element of each tuple should be a section name, and the second element should be an option name. Whenever a section and option is requested, not found in the configuration file, and found in defaultValues, the value from defaultValues will be returned and written to the file in the appropriate place.

preserveCase : bool

Whether the names of the sections and options should preserve case.

Methods

get(section, option, default=None, converter=None)

Read a value from the configuration file.

Attempt to read a value from the configuration file under the section section and associated with the key option. If either of these is missing from the file, search the dictionary of default values. If either the section or the key is missing from that dictionary, also, return default.

If the file format is FORMAT_BASIC and the requested item is found in the file, return the string from the file, passed through converter if it is specified.

If the file format is FORMAT_REPR and the requested item is found in the file, return the value from the file, passed first through eval and then, if it is specified, through converter.

If the file format is FORMAT_AUTO and the requested item is found in the file, attempt to guess the type of the data in the file, cast the data to that type, and return it, passing it through converter if it is specified.

If the requested data is not found in the file, return the appropriate element from the dictionary of default values, passed through converter if it is specified.

If the requested data is not found in either the file or the defaults dictionary, return default, passed through converter if it is specified.

Finally, after any/all conversions have taken place, write the value that will be returned to the configuration file and return said value.

In summary,

• converter, if specified, takes precedence over all other data type casting; and
• the search order is (1) the configuration file, (2) the dictionary of default values, and (3) the default supplied to this method.

Parameters :

section : string

The section from which the value should be read.

option : string

The item within the specified section whose value should be read.

default : (variant)

The value to return if the specified section or option does not exist in either the file or the dictionary of default values.

converter : function

A function to convert the value to the appropriate type.

Returns :

(variant) :

The value associated with section and option in the configuration file.

getBoolean(section, option, default=False)

Return a value from the configuration file as a boolean.

Parameters :

section : string

The section from which the value should be read.

option : string

The item within the specified section whose value should be read.

default : bool

The value to return if the specified section or option does not exist in either the file or the dictionary of default values.

Returns :

bool :

The boolean associated with the specified section and key, or default if no such entry exists.

getFloat(section, option, default=0)

Return a value from the configuration file as a float.

Parameters :

section : string

The section from which the value should be read.

option : string

The item within the specified section whose value should be read.

default : float

The value to return if the specified section or option does not exist in either the file or the dictionary of default values.

Returns :

int :

The float associated with the specified section and key, or default if no such entry exists.

getInt(section, option, default=0)

Return a value from the configuration file as an integer.

Parameters :

section : string

The section from which the value should be read.

option : string

The item within the specified section whose value should be read.

default : int

The value to return if the specified section or option does not exist in either the file or the dictionary of default values.

Returns :

int :

The integer associated with the specified section and key, or default if no such entry exists.

getOptions(section)

Return a list of options under a specified section.

Return a list of strings specifying the keys contained within a specified section, including the information from both the defaults dictionary and the configuration file. Each option will occur only once.

Parameters :

section : str

The section whose options should be retrieved.

Returns :

list of str :

A list of strings indicating the options listed under the specified section.

getOptionsDict(section)

Return a dictionary containing the options and values in a section.

Parameters :

section : str

The section whose values should be returned.

Returns :

dict :

A dictionary containing the names of the options in the specified section and the values associated with those options.

getSections()

Return a list of available sections.

Returns :

list of str :

A list of strings specifying the sections included in both the configuration file and the dictionary of default values.

set(section, option, value)

Write a value to the configuration file.

If the file format is FORMAT_REPR, pass value through the repr function before writing it.

Parameters :

section : str

The section within the file which should contain the option to be written.

option : str

The key within section with which the data should be associated.

value : (variant)

The value to be associated with the given key in the given section.