1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313
|
\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.
\begin{classdesc}{RawConfigParser}{\optional{defaults}}
The basic configuration object. When \var{defaults} is given, it is
initialized into the dictionary of intrinsic defaults. This class
does not support the magical interpolation behavior.
\versionadded{2.3}
\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}
|