323 lines
12 KiB
TeX
323 lines
12 KiB
TeX
\section{\module{ConfigParser} ---
|
|
Configuration file parser}
|
|
|
|
\declaremodule{standard}{ConfigParser}
|
|
\modulesynopsis{Configuration file parser.}
|
|
\moduleauthor{Ken Manheimer}{klm@zope.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.
|
|
|
|
\begin{notice}[warning]
|
|
This library does \emph{not} interpret or write the value-type
|
|
prefixes used in the Windows Registry extended version of INI syntax.
|
|
\end{notice}
|
|
|
|
The configuration file consists of sections, led 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 on
|
|
initialization and retrieval. Lines beginning with \character{\#} or
|
|
\character{;} are ignored and may be used to provide comments.
|
|
|
|
For example:
|
|
|
|
\begin{verbatim}
|
|
[My Section]
|
|
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.
|
|
|
|
Sections are normally stored in a builtin dictionary. An alternative
|
|
dictionary type can be passed to the \class{ConfigParser} constructor.
|
|
For example, if a dictionary type is passed that sorts is keys,
|
|
the sections will be sorted on write-back, as will be the keys within
|
|
each section.
|
|
|
|
\begin{classdesc}{RawConfigParser}{\optional{defaults\optional{, dict_type}}}
|
|
The basic configuration object. When \var{defaults} is given, it is
|
|
initialized into the dictionary of intrinsic defaults. When \var{dict_type}
|
|
is given, it will be used to create the dictionary objects for the list
|
|
of sections, for the options within a section, and for the default values.
|
|
This class does not support the magical interpolation behavior.
|
|
\versionadded{2.3}
|
|
\versionchanged[\var{dict_type} was added]{2.6}
|
|
\end{classdesc}
|
|
|
|
\begin{classdesc}{ConfigParser}{\optional{defaults}}
|
|
Derived class of \class{RawConfigParser} that implements the magical
|
|
interpolation feature and adds optional arguments to the \method{get()}
|
|
and \method{items()} methods. The values in \var{defaults} 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}.
|
|
|
|
All option names used in interpolation will be passed through the
|
|
\method{optionxform()} method just like any other option name
|
|
reference. For example, using the default implementation of
|
|
\method{optionxform()} (which converts option names to lower case),
|
|
the values \samp{foo \%(bar)s} and \samp{foo \%(BAR)s} are
|
|
equivalent.
|
|
\end{classdesc}
|
|
|
|
\begin{classdesc}{SafeConfigParser}{\optional{defaults}}
|
|
Derived class of \class{ConfigParser} that implements a more-sane
|
|
variant of the magical interpolation feature. This implementation is
|
|
more predictable as well.
|
|
% XXX Need to explain what's safer/more predictable about it.
|
|
New applications should prefer this version if they don't need to be
|
|
compatible with older versions of Python.
|
|
\versionadded{2.3}
|
|
\end{classdesc}
|
|
|
|
\begin{excdesc}{NoSectionError}
|
|
Exception raised when a specified section is not found.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{DuplicateSectionError}
|
|
Exception raised 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}
|
|
Base class for exceptions 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}.
|
|
Subclass of \exception{InterpolationError}.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{InterpolationMissingOptionError}
|
|
Exception raised when an option referenced from a value does not exist.
|
|
Subclass of \exception{InterpolationError}.
|
|
\versionadded{2.3}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{InterpolationSyntaxError}
|
|
Exception raised when the source text into which substitutions are
|
|
made does not conform to the required syntax.
|
|
Subclass of \exception{InterpolationError}.
|
|
\versionadded{2.3}
|
|
\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. This is relevant only for the
|
|
\class{ConfigParser} class.
|
|
\end{datadesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seemodule{shlex}{Support for a creating \UNIX{} shell-like
|
|
mini-languages which can be used as an alternate
|
|
format for application configuration files.}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{RawConfigParser Objects \label{RawConfigParser-objects}}
|
|
|
|
\class{RawConfigParser} 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 \constant{True}; otherwise return \constant{False}.
|
|
\versionadded{1.6}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read}{filenames}
|
|
Attempt to read and parse a list of filenames, returning a list of filenames
|
|
which were successfully parsed. If \var{filenames} is a string or
|
|
Unicode string, it is treated as a single filename.
|
|
If a file named in \var{filenames} cannot be opened, that file will be
|
|
ignored. This is designed so that you can specify a list of potential
|
|
configuration file locations (for example, the current directory, the
|
|
user's home directory, and some system-wide directory), and all
|
|
existing configuration files in the list will be read. If none of the
|
|
named files exist, the \class{ConfigParser} instance will contain an
|
|
empty dataset. An application which requires initial values to be
|
|
loaded from a file should load the required file or files using
|
|
\method{readfp()} before calling \method{read()} for any optional
|
|
files:
|
|
|
|
\begin{verbatim}
|
|
import ConfigParser, os
|
|
|
|
config = ConfigParser.ConfigParser()
|
|
config.readfp(open('defaults.cfg'))
|
|
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
|
|
\end{verbatim}
|
|
\versionchanged[Returns list of successfully parsed filenames]{2.4}
|
|
\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}
|
|
Get an \var{option} value for the named \var{section}.
|
|
\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 \code{True}, and \code{"0"}, \code{"no"},
|
|
\code{"false"}, and \code{"off"}, which cause it to return \code{False}. These
|
|
string values are checked in a case-insensitive manner. Any other value will
|
|
cause it to raise \exception{ValueError}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{items}{section}
|
|
Return a list of \code{(\var{name}, \var{value})} pairs for each
|
|
option in the given \var{section}.
|
|
\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}. While it is
|
|
possible to use \class{RawConfigParser} (or \class{ConfigParser} with
|
|
\var{raw} parameters set to true) for \emph{internal} storage of
|
|
non-string values, full functionality (including interpolation and
|
|
output to files) can only be achieved using string values.
|
|
\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 \constant{True};
|
|
otherwise return \constant{False}.
|
|
\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 \code{True}.
|
|
Otherwise return \code{False}.
|
|
\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}
|
|
|
|
|
|
\subsection{ConfigParser Objects \label{ConfigParser-objects}}
|
|
|
|
The \class{ConfigParser} class extends some methods of the
|
|
\class{RawConfigParser} interface, adding some optional arguments.
|
|
|
|
\begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
|
|
Get an \var{option} value for the named \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}{items}{section\optional{, raw\optional{, vars}}}
|
|
Return a list of \code{(\var{name}, \var{value})} pairs for each
|
|
option in the given \var{section}. Optional arguments have the
|
|
same meaning as for the \method{get()} method.
|
|
\versionadded{2.3}
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{SafeConfigParser Objects \label{SafeConfigParser-objects}}
|
|
|
|
The \class{SafeConfigParser} class implements the same extended
|
|
interface as \class{ConfigParser}, with the following addition:
|
|
|
|
\begin{methoddesc}{set}{section, option, value}
|
|
If the given section exists, set the given option to the specified
|
|
value; otherwise raise \exception{NoSectionError}. \var{value} must
|
|
be a string (\class{str} or \class{unicode}); if not,
|
|
\exception{TypeError} is raised.
|
|
\versionadded{2.4}
|
|
\end{methoddesc}
|