\section{\module{ConfigParser} --- Configuration file parser} \declaremodule{standard}{ConfigParser} \modulesynopsis{Configuration file parser.} \moduleauthor{Ken Manheimer}{klm@digicool.com} \moduleauthor{Barry Warsaw}{bwarsaw@python.org} \moduleauthor{Eric S. Raymond}{esr@thyrsus.com} \sectionauthor{Christopher G. Petrilli}{petrilli@amber.org} This module defines the class \class{ConfigParser}. \indexii{.ini}{file}\indexii{configuration}{file}\index{ini file} \index{Windows ini file} The \class{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. The configuration file consists of sections, lead by a \samp{[section]} header and followed by \samp{name: value} entries, with continuations in the style of \rfc{822}; \samp{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 \code{DEFAULT} section. Additional defaults can be provided upon initialization and retrieval. Lines beginning with \character{\#} or \character{;} are ignored and may be used to provide comments. For example: \begin{verbatim} foodir: %(dir)s/whatever dir=frob \end{verbatim} would resolve the \samp{\%(dir)s} to the value of \samp{dir} (\samp{frob} in this case). All reference expansions are done on demand. Default values can be specified by passing them into the \class{ConfigParser} constructor as a dictionary. Additional defaults may be passed into the \method{get()} method which will override all others. \begin{classdesc}{ConfigParser}{\optional{defaults}} Return a new instance of the \class{ConfigParser} class. When \var{defaults} is given, it is initialized into the dictionary of intrinsic defaults. The keys must be strings, and the values must be appropriate for the \samp{\%()s} string interpolation. Note that \var{__name__} is an intrinsic default; its value is the section name, and will override any value provided in \var{defaults}. \end{classdesc} \begin{excdesc}{NoSectionError} Exception raised when a specified section is not found. \end{excdesc} \begin{excdesc}{DuplicateSectionError} Exception raised when multiple sections with the same name are found, or if \method{add_section()} is called with the name of a section that is already present. \end{excdesc} \begin{excdesc}{NoOptionError} Exception raised when a specified option is not found in the specified section. \end{excdesc} \begin{excdesc}{InterpolationError} Exception raised when problems occur performing string interpolation. \end{excdesc} \begin{excdesc}{InterpolationDepthError} Exception raised when string interpolation cannot be completed because the number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}. \end{excdesc} \begin{excdesc}{MissingSectionHeaderError} Exception raised when attempting to parse a file which has no section headers. \end{excdesc} \begin{excdesc}{ParsingError} Exception raised when errors occur attempting to parse a file. \end{excdesc} \begin{datadesc}{MAX_INTERPOLATION_DEPTH} The maximum depth for recursive interpolation for \method{get()} when the \var{raw} parameter is false. Setting this does not change the allowed recursion depth. \end{datadesc} \begin{seealso} \seemodule{shlex}{Support for a creating \UNIX{} shell-like minilanguages which can be used as an alternate format for application configuration files.} \end{seealso} \subsection{ConfigParser Objects \label{ConfigParser-objects}} \class{ConfigParser} instances have the following methods: \begin{methoddesc}{defaults}{} Return a dictionary containing the instance-wide defaults. \end{methoddesc} \begin{methoddesc}{sections}{} Return a list of the sections available; \code{DEFAULT} is not included in the list. \end{methoddesc} \begin{methoddesc}{add_section}{section} Add a section named \var{section} to the instance. If a section by the given name already exists, \exception{DuplicateSectionError} is raised. \end{methoddesc} \begin{methoddesc}{has_section}{section} Indicates whether the named section is present in the configuration. The \code{DEFAULT} section is not acknowledged. \end{methoddesc} \begin{methoddesc}{options}{section} Returns a list of options available in the specified \var{section}. \end{methoddesc} \begin{methoddesc}{has_option}{section, option} If the given section exists, and contains the given option. return 1; otherwise return 0. \versionadded{1.6} \end{methoddesc} \begin{methoddesc}{read}{filenames} Read and parse a list of filenames. If \var{filenames} is a string or Unicode string, it is treated as a single filename. \end{methoddesc} \begin{methoddesc}{readfp}{fp\optional{, filename}} Read and parse configuration data from the file or file-like object in \var{fp} (only the \method{readline()} method is used). If \var{filename} is omitted and \var{fp} has a \member{name} attribute, that is used for \var{filename}; the default is \samp{}. \end{methoddesc} \begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}} Get an \var{option} value for the provided \var{section}. All the \character{\%} interpolations are expanded in the return values, based on the defaults passed into the constructor, as well as the options \var{vars} provided, unless the \var{raw} argument is true. \end{methoddesc} \begin{methoddesc}{getint}{section, option} A convenience method which coerces the \var{option} in the specified \var{section} to an integer. \end{methoddesc} \begin{methoddesc}{getfloat}{section, option} A convenience method which coerces the \var{option} in the specified \var{section} to a floating point number. \end{methoddesc} \begin{methoddesc}{getboolean}{section, option} A convenience method which coerces the \var{option} in the specified \var{section} to a Boolean value. Note that the accepted values for the option are \code{1}, \code{yes}, \code{true}, and \code{on}, which cause this method to return true, and \code{0}, \code{no}, \code{false}, and \code{off}, which cause it to return false. These values are checked in a case-insensitive manner. Any other value will cause it to raise \exception{ValueError}. \end{methoddesc} \begin{methoddesc}{set}{section, option, value} If the given section exists, set the given option to the specified value; otherwise raise \exception{NoSectionError}. \versionadded{1.6} \end{methoddesc} \begin{methoddesc}{write}{fileobject} Write a representation of the configuration to the specified file object. This representation can be parsed by a future \method{read()} call. \versionadded{1.6} \end{methoddesc} \begin{methoddesc}{remove_option}{section, option} Remove the specified \var{option} from the specified \var{section}. If the section does not exist, raise \exception{NoSectionError}. If the option existed to be removed, return 1; otherwise return 0. \versionadded{1.6} \end{methoddesc} \begin{methoddesc}{remove_section}{section} Remove the specified \var{section} from the configuration. If the section in fact existed, return 1. Otherwise return 0. \end{methoddesc} \begin{methoddesc}{optionxform}{option} Transforms the option name \var{option} as found in an input file or as passed in by client code to the form that should be used in the internal structures. The default implementation returns a lower-case version of \var{option}; subclasses may override this or client code can set an attribute of this name on instances to affect this behavior. Setting this to \function{str()}, for example, would make option names case sensitive. \end{methoddesc}