mirror of
https://github.com/python/cpython.git
synced 2024-12-01 03:01:36 +01:00
129 lines
4.5 KiB
TeX
129 lines
4.5 KiB
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}
|