2.3 Adding Options

The add_option() method of ConfigParser is used to add configuration options to the parser. This is the same concept as adding options with the optparse module and shares many of the same arguments (please bring any inconsistencies to the attention of the author). Defining the options in the configuration parser serves the following purposes:

automatic type and value checking
default values can be defined
help can be automatically generated in a consistent format

Options must be added to the parser before the parse() method is called. Options may be added before or after files are added to the parser. The following is the add_option() method prototype:

add_option( name[, help][, type][, choices][, dest][, metavar][, default][, check][, keys])

name is a positional string argument and is the exact name of the configuration option as it is to appear in the configuration file.

help is an optional string keyword argument and controls the help text associated with this option displayed when configuration help is written. Defaults to None which displays no additional help text beyond the option name and metavar. This may be set to cfgparse.SUPPRESS_HELP to completely eliminate the option from the help text. See "Option help" (section 2.3.4) details. If using optparse and cfgparse in cooperation, help may be omitted here and will automatically be picked up from the optparse option. See "Option cooperation" (section 3.2) for more details.

type is an optional string keyword argument and describes the type which the configuration option is to be converted into. See "Option type" (section 2.3.2) for details. If using optparse and cfgparse in cooperation, type may be omitted here and will automatically be picked up from the optparse option. See "Option cooperation" (section 3.2) for more details.

choices is an optional list keyword argument and is used to pass in the possible choices when type is set to 'choice'. See "Option type" (section 2.3.2) for details. If using optparse and cfgparse in cooperation, choices may be omitted here and will automatically be picked up from the optparse option. See "Option cooperation" (section 3.2) for more details.

dest is an optional string keyword argument and controls the attribute name that the value of this option will be stored in when the parse() method creates an options object. This must be a unique value for every added option. Default is None which will cause the name argument to be used as the destination attribute. See "Name and destination" (section 2.3.1) for more details. If using optparse and cfgparse in cooperation, dest must exactly match between the two options. See "Option cooperation" (section 3.2) for more details.

metavar is an optional string keyword argument and is used control the help text associated with this option. Specifically, this text string is used directly after the ('=') sign in the option=VALUE. By default the dest argument in all upper case is used. If using optparse and cfgparse in cooperation, metavar may be omitted here and will automatically be picked up from the optparse option. See "Option cooperation" (section 3.2) for more details.

default is an optional keyword argument and is used control the configuration option default value when the configuration option cannot be found. Omitting this option will cause an exception to be raised when the option cannot be found. If using optparse and cfgparse in cooperation, default should NOT be set when adding the optparse option. See "Option cooperation" (section 3.2) for more details.

check is an optional keyword argument and is used to pass in a function to validate (and possibly convert) the configuration option. Function interface requirements are defined in "Option check" (section 2.3.3).

keys is an optional argument and is used to pass in the section keys to obtain the option. Typically this is set to the section name where the setting is expected to be (the [DEFAULT] section will also be searched as a last resort). Default is None which will cause the parser only obtain the option setting from the [DEFAULT] section. See "Keys" (section 6) for more details.