General

It will not be described here how to construct an option parser with a list of options, it is assumed you have basic knowledge on how to do this. If not, it is recommended that you read the documentation for the optparse module before you proceed.

In order to be able to read configfiles, configparse adds a keyword files to the parse_args() method of the OptionParser. The files argument accepts a sequence of filenames or file objects opened for reading. parse_args() will not raise an error if a filename does not refer to an existing or readable file - this allows reading configfiles from a standard set of locations. The values parse_args() returns are collected in the following order:

default values -> config files -> command-line parameters

So, the options passed on the command-line will always supersede values read from configfiles.

configparse discriminates between three different kinds of options: options that will be accepted on the command-line, options that can only be read from configfiles and those that will be accepted on both command-line and from configfiles. This behaviour is controlled using the configparse-specific config keyword together with add_option() or the Option() constructor.

The dest keyword plays an important role, too. Besides defining the option's attribute name in the Values object that is returned by parse_args(), it also provides the name by which the option is referenced in the configfile.

It is also possible to write a representation of the parser's values to a writable file object using its write() method.

Configfile Errors

In case of errors in configfiles configparse knows three possible reactions which can be set with the error_handler keyword to the OptionParser constructor or with the set_error_handler() method:

1. 'error' (which is the default) will print an error message to stderr and terminate the running program with an exit status of 2. In other words, it calls the error method of OptionParser.
2. 'warn' will print an error message for every error to stderr without terminating the program.
3. 'ignore' will simply ignore errors without any output.

Internals

There are some constraints involved because the configparse module is built around optparse which is focused on command-line parsing and not processing configfiles:

1. The configfile feature is disabled for the following action types: 'help', 'version' and 'callback'.
2. The types of constants in store_const options must be builtin non-sequence types.
3. If there is a default value set for an append option, values that are read from a configfile are not appended to it but the default value is replaced.
4. Since optparse does not enforce consistency among Option objects that access the same dest value, configparse tries to do its best to discern the one Option object which has the least strict type.

The config keyword

The config keyword accepts the following values:

1. 'false' or None: This is the default and the same as if the keyword argument would have been omitted. This option will be accepted solely on the command-line. A BadOptionError will be raised when the parser encounters the option's name in a configuration file. It will not be written to the file by write() either.
2. 'only': This way the option will only be accepted as part of a configfile. The attempt to define option strings will provoke an OptionError. Because this is not allowed, it will not be possible to pass this option on the command-line. Furthermore such options will not appear in help output.
3. 'true': This is probably the most common case. The option will be accepted both on command-line and in configfiles.

Example

The following example illustrates how to use configparse in your own program, in this case called program.py:

import os
from configparse import OptionParser

parser = OptionParser()

# Read this option from both the command line and the config file (config="true").
parser.add_option("-d", "--directory", action="store", type="string",
                  dest="directory", default="/home/foo", help="...",
                  config="true")

# Read this option only from the command line (config="false" is omitted in this
# case because it is the default).
parser.add_option("-v", "--verbose", action="store_true", dest="verbose",
                  help="...", default=False)

# Read this option only from the config file (config="only"). Note that there are no
# option strings allowed. This option will not appear in help output.
parser.add_option(action="store_true", dest="debug", default=False,
                  help="...", config="only")

opts, args = parser.parse_args(files=[os.path.expanduser("~/.programrc")])

print opts.directory
print opts.verbose
print opts.debug

Call program.py without arguments, it will print the default values:

$ program.py
/home/foo
False
False

Create a file ~/.programrc:

# This is a comment.
; This is a comment, too.
directory = "/home/bar"
debug = True

Call program.py a few more times:

$ program
/home/bar
False
True

$ program.py --directory /home/baz
/home/baz
False
True

$ program.py -v
/home/bar
True
True