Doc/lib/libcfgparser.tex

\section{\module{ConfigParser} ---
         Configuration file parser}

\declaremodule{standard}{ConfigParser}
\modulesynopsis{Configuration file parser.}
\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.  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{\#} are 
ignored and may be used to provide comments.

For example:

\begin{verbatim}
foodir: %(dir)s/whatever
\end{verbatim}

would resolve the \samp{\%(dir)s} to the value of dir. All reference
expansions are done late, on demand.

Intrinsic defaults 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 dictionairy of
intrinsic defaults.  They keys must be strings, and the values must be 
appropriate for the \samp{\%()s} string interpolation.  Note that
\var{__name__} is always an intrinsic default; its value is the 
section name.
\end{classdesc}

\begin{excdesc}{NoSectionError}
Exception raised when a specified section is not found.
\end{excdesc}

\begin{excdesc}{DuplicateSectionError}
Exception raised when mutliple sections with the same name are found.
\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}{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{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 dictionairy containing the instance-wide defaults.
\end{methoddesc}

\begin{methoddesc}{sections}{}
Return a list of the sections available.
\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}{read}{filenames}
Read and parse a list of filenames.
\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 only accepted values
for the option are \code{0} and \code{1}, any others will raise
\exception{ValueError}.
\end{methoddesc}