9.2 ConfigParser -- Configuration file parser

# 9.2 `ConfigParser` -- Configuration file parser

This module defines the class `ConfigParser`. The `ConfigParser` class implements a basic configuration file parser language which provides a structure similar to what you would find on Microsoft Windows INI files. You can use this to write Python programs which can be customized by end users easily.

Warning: This library does not interpret or write the value-type prefixes used in the Windows Registry extended version of INI syntax.

The configuration file consists of sections, led by a "`[section]`" header and followed by "`name: value`" entries, with continuations in the style of RFC 822; "`name=value`" is also accepted. Note that leading whitespace is removed from values. The optional values can contain format strings which refer to other values in the same section, or values in a special `DEFAULT` section. Additional defaults can be provided on initialization and retrieval. Lines beginning with "`#`" or "`;`" are ignored and may be used to provide comments.

For example:

    [My Section]
    foodir: %(dir)s/whatever
    dir=frob

would resolve the "`%(dir)s`" to the value of "`dir`" ("`frob`" in this case). All reference expansions are done on demand.

Default values can be specified by passing them into the `ConfigParser` constructor as a dictionary. Additional defaults may be passed into the `get()` method which will override all others.

class `RawConfigParser`( | [defaults])

  The basic configuration object. When defaults is given, it is initialized into the dictionary of intrinsic defaults. This class does not support the magical interpolation behavior. New in version 2.3.

class `ConfigParser`( | [defaults])

  Derived class of `RawConfigParser` that implements the magical interpolation feature and adds optional arguments to the `get()` and `items()` methods. The values in defaults must be appropriate for the "`%()s`" string interpolation. Note that __name__ is an intrinsic default; its value is the section name, and will override any value provided in defaults.

  All option names used in interpolation will be passed through the `optionxform()` method just like any other option name reference. For example, using the default implementation of `optionxform()` (which converts option names to lower case), the values "`foo %(bar)s`" and "`foo %(BAR)s`" are equivalent.

class `SafeConfigParser`( | [defaults])

  Derived class of `ConfigParser` that implements a more-sane variant of the magical interpolation feature. This implementation is more predictable as well. New applications should prefer this version if they don't need to be compatible with older versions of Python. New in version 2.3.

exception `NoSectionError`
  Exception raised when a specified section is not found.

exception `DuplicateSectionError`
  Exception raised if `add_section()` is called with the name of a section that is already present.

exception `NoOptionError`
  Exception raised when a specified option is not found in the specified section.

exception `InterpolationError`
  Base class for exceptions raised when problems occur performing string interpolation.

exception `InterpolationDepthError`
  Exception raised when string interpolation cannot be completed because the number of iterations exceeds `MAX_INTERPOLATION_DEPTH`. Subclass of `InterpolationError`.

exception `InterpolationMissingOptionError`
  Exception raised when an option referenced from a value does not exist. Subclass of `InterpolationError`. New in version 2.3.

exception `InterpolationSyntaxError`
  Exception raised when the source text into which substitutions are made does not conform to the required syntax. Subclass of `InterpolationError`. New in version 2.3.

exception `MissingSectionHeaderError`
  Exception raised when attempting to parse a file which has no section headers.

exception `ParsingError`
  Exception raised when errors occur attempting to parse a file.

`MAX_INTERPOLATION_DEPTH`
  The maximum depth for recursive interpolation for `get()` when the raw parameter is false. This is relevant only for the `ConfigParser` class.

See Also:

Module `shlex`:
  Support for a creating Unix shell-like mini-languages which can be used as an alternate format for application configuration files.