Doc/lib/libcfgparser.tex

   1 \section{\module{ConfigParser} ---
   2          Configuration file parser}
   3
   4 \declaremodule{standard}{ConfigParser}
   5 \modulesynopsis{Configuration file parser.}
   6 \moduleauthor{Ken Manheimer}{klm@digicool.com}
   7 \moduleauthor{Barry Warsaw}{bwarsaw@python.org}
   8 \moduleauthor{Eric S. Raymond}{esr@thyrsus.com}
   9 \sectionauthor{Christopher G. Petrilli}{petrilli@amber.org}
  10
  11 This module defines the class \class{ConfigParser}.
  12 \indexii{.ini}{file}\indexii{configuration}{file}\index{ini file}
  13 \index{Windows ini file}
  14 The \class{ConfigParser} class implements a basic configuration file
  15 parser language which provides a structure similar to what you would
  16 find on Microsoft Windows INI files.  You can use this to write Python
  17 programs which can be customized by end users easily.
  18
  19 \begin{notice}[warning]
  20   This library does \emph{not} interpret or write the value-type
  21   prefixes used in the Windows Registry extended version of INI syntax.
  22 \end{notice}
  23
  24 The configuration file consists of sections, led by a
  25 \samp{[section]} header and followed by \samp{name: value} entries,
  26 with continuations in the style of \rfc{822}; \samp{name=value} is
  27 also accepted.  Note that leading whitespace is removed from values.
  28 The optional values can contain format strings which refer to other
  29 values in the same section, or values in a special
  30 \code{DEFAULT} section.  Additional defaults can be provided on
  31 initialization and retrieval.  Lines beginning with \character{\#} or
  32 \character{;} are ignored and may be used to provide comments.
  33
  34 For example:
  35
  36 \begin{verbatim}
  37 [My Section]
  38 foodir: %(dir)s/whatever
  39 dir=frob
  40 \end{verbatim}
  41
  42 would resolve the \samp{\%(dir)s} to the value of
  43 \samp{dir} (\samp{frob} in this case).  All reference expansions are
  44 done on demand.
  45
  46 Default values can be specified by passing them into the
  47 \class{ConfigParser} constructor as a dictionary.  Additional defaults
  48 may be passed into the \method{get()} method which will override all
  49 others.
  50
  51 \begin{classdesc}{RawConfigParser}{\optional{defaults}}
  52 The basic configuration object.  When \var{defaults} is given, it is
  53 initialized into the dictionary of intrinsic defaults.  This class
  54 does not support the magical interpolation behavior.
  55 \versionadded{2.3}
  56 \end{classdesc}
  57
  58 \begin{classdesc}{ConfigParser}{\optional{defaults}}
  59 Derived class of \class{RawConfigParser} that implements the magical
  60 interpolation feature and adds optional arguments the \method{get()}
  61 and \method{items()} methods.  The values in \var{defaults} must be
  62 appropriate for the \samp{\%()s} string interpolation.  Note that
  63 \var{__name__} is an intrinsic default; its value is the section name,
  64 and will override any value provided in \var{defaults}.
  65 \end{classdesc}
  66
  67 \begin{classdesc}{SafeConfigParser}{\optional{defaults}}
  68 Derived class of \class{ConfigParser} that implements a more-sane
  69 variant of the magical interpolation feature.  This implementation is
  70 more predictable as well.
  71 % XXX Need to explain what's safer/more predictable about it.
  72 New applications should prefer this version if they don't need to be
  73 compatible with older versions of Python.
  74 \versionadded{2.3}
  75 \end{classdesc}
  76
  77 \begin{excdesc}{NoSectionError}
  78 Exception raised when a specified section is not found.
  79 \end{excdesc}
  80
  81 \begin{excdesc}{DuplicateSectionError}
  82 Exception raised when multiple sections with the same name are found,
  83 or if \method{add_section()} is called with the name of a section that
  84 is already present.
  85 \end{excdesc}
  86
  87 \begin{excdesc}{NoOptionError}
  88 Exception raised when a specified option is not found in the specified
  89 section.
  90 \end{excdesc}
  91
  92 \begin{excdesc}{InterpolationError}
  93 Base class for exceptions raised when problems occur performing string
  94 interpolation.
  95 \end{excdesc}
  96
  97 \begin{excdesc}{InterpolationDepthError}
  98 Exception raised when string interpolation cannot be completed because
  99 the number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}.
 100 Subclass of \exception{InterpolationError}.
 101 \end{excdesc}
 102
 103 \begin{excdesc}{InterpolationMissingOptionError}
 104 Exception raised when an option referenced from a value does not exist.
 105 Subclass of \exception{InterpolationError}.
 106 \versionadded{2.3}
 107 \end{excdesc}
 108
 109 \begin{excdesc}{InterpolationSyntaxError}
 110 Exception raised when the source text into which substitutions are
 111 made does not conform to the required syntax.
 112 Subclass of \exception{InterpolationError}.
 113 \versionadded{2.3}
 114 \end{excdesc}
 115
 116 \begin{excdesc}{MissingSectionHeaderError}
 117 Exception raised when attempting to parse a file which has no section
 118 headers.
 119 \end{excdesc}
 120
 121 \begin{excdesc}{ParsingError}
 122 Exception raised when errors occur attempting to parse a file.
 123 \end{excdesc}
 124
 125 \begin{datadesc}{MAX_INTERPOLATION_DEPTH}
 126 The maximum depth for recursive interpolation for \method{get()} when
 127 the \var{raw} parameter is false.  This is relevant only for the
 128 \class{ConfigParser} class.
 129 \end{datadesc}
 130
 131
 132 \begin{seealso}
 133   \seemodule{shlex}{Support for a creating \UNIX{} shell-like
 134                     mini-languages which can be used as an alternate
 135                     format for application configuration files.}
 136 \end{seealso}
 137
 138
 139 \subsection{RawConfigParser Objects \label{RawConfigParser-objects}}
 140
 141 \class{RawConfigParser} instances have the following methods:
 142
 143 \begin{methoddesc}{defaults}{}
 144 Return a dictionary containing the instance-wide defaults.
 145 \end{methoddesc}
 146
 147 \begin{methoddesc}{sections}{}
 148 Return a list of the sections available; \code{DEFAULT} is not
 149 included in the list.
 150 \end{methoddesc}
 151
 152 \begin{methoddesc}{add_section}{section}
 153 Add a section named \var{section} to the instance.  If a section by
 154 the given name already exists, \exception{DuplicateSectionError} is
 155 raised.
 156 \end{methoddesc}
 157
 158 \begin{methoddesc}{has_section}{section}
 159 Indicates whether the named section is present in the
 160 configuration. The \code{DEFAULT} section is not acknowledged.
 161 \end{methoddesc}
 162
 163 \begin{methoddesc}{options}{section}
 164 Returns a list of options available in the specified \var{section}.
 165 \end{methoddesc}
 166
 167 \begin{methoddesc}{has_option}{section, option}
 168 If the given section exists, and contains the given option. return 1;
 169 otherwise return 0.
 170 \versionadded{1.6}
 171 \end{methoddesc}
 172
 173 \begin{methoddesc}{read}{filenames}
 174 Read and parse a list of filenames.  If \var{filenames} is a string or
 175 Unicode string, it is treated as a single filename.
 176 If a file named in \var{filenames} cannot be opened, that file will be
 177 ignored.  This is designed so that you can specify a list of potential
 178 configuration file locations (for example, the current directory, the
 179 user's home directory, and some system-wide directory), and all
 180 existing configuration files in the list will be read.  If none of the
 181 named files exist, the \class{ConfigParser} instance will contain an
 182 empty dataset.  An application which requires initial values to be
 183 loaded from a file should load the required file or files using
 184 \method{readfp()} before calling \method{read()} for any optional
 185 files:
 186
 187 \begin{verbatim}
 188 import ConfigParser, os
 189
 190 config = ConfigParser.ConfigParser()
 191 config.readfp(open('defaults.cfg'))
 192 config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
 193 \end{verbatim}
 194 \end{methoddesc}
 195
 196 \begin{methoddesc}{readfp}{fp\optional{, filename}}
 197 Read and parse configuration data from the file or file-like object in
 198 \var{fp} (only the \method{readline()} method is used).  If
 199 \var{filename} is omitted and \var{fp} has a \member{name} attribute,
 200 that is used for \var{filename}; the default is \samp{<???>}.
 201 \end{methoddesc}
 202
 203 \begin{methoddesc}{get}{section, option}
 204 Get an \var{option} value for the named \var{section}.
 205 \end{methoddesc}
 206
 207 \begin{methoddesc}{getint}{section, option}
 208 A convenience method which coerces the \var{option} in the specified
 209 \var{section} to an integer.
 210 \end{methoddesc}
 211
 212 \begin{methoddesc}{getfloat}{section, option}
 213 A convenience method which coerces the \var{option} in the specified
 214 \var{section} to a floating point number.
 215 \end{methoddesc}
 216
 217 \begin{methoddesc}{getboolean}{section, option}
 218 A convenience method which coerces the \var{option} in the specified
 219 \var{section} to a Boolean value.  Note that the accepted values
 220 for the option are \code{1}, \code{yes}, \code{true}, and \code{on},
 221 which cause this method to return true, and \code{0}, \code{no},
 222 \code{false}, and \code{off}, which cause it to return false.  These
 223 values are checked in a case-insensitive manner.  Any other value will
 224 cause it to raise \exception{ValueError}.
 225 \end{methoddesc}
 226
 227 \begin{methoddesc}{items}{section}
 228 Return a list of \code{(\var{name}, \var{value})} pairs for each
 229 option in the given \var{section}.
 230 \end{methoddesc}
 231
 232 \begin{methoddesc}{set}{section, option, value}
 233 If the given section exists, set the given option to the specified value;
 234 otherwise raise \exception{NoSectionError}.
 235 \versionadded{1.6}
 236 \end{methoddesc}
 237
 238 \begin{methoddesc}{write}{fileobject}
 239 Write a representation of the configuration to the specified file
 240 object.  This representation can be parsed by a future \method{read()}
 241 call.
 242 \versionadded{1.6}
 243 \end{methoddesc}
 244
 245 \begin{methoddesc}{remove_option}{section, option}
 246 Remove the specified \var{option} from the specified \var{section}.
 247 If the section does not exist, raise \exception{NoSectionError}.
 248 If the option existed to be removed, return 1; otherwise return 0.
 249 \versionadded{1.6}
 250 \end{methoddesc}
 251
 252 \begin{methoddesc}{remove_section}{section}
 253 Remove the specified \var{section} from the configuration.
 254 If the section in fact existed, return \code{True}.
 255 Otherwise return \code{False}.
 256 \end{methoddesc}
 257
 258 \begin{methoddesc}{optionxform}{option}
 259 Transforms the option name \var{option} as found in an input file or
 260 as passed in by  client code to the form that should be used in the
 261 internal structures.  The default implementation returns a lower-case
 262 version of \var{option}; subclasses may override this or client code
 263 can set an attribute of this name on instances to affect this
 264 behavior.  Setting this to \function{str()}, for example, would make
 265 option names case sensitive.
 266 \end{methoddesc}
 267
 268
 269 \subsection{ConfigParser Objects \label{ConfigParser-objects}}
 270
 271 The \class{ConfigParser} class extends some methods of the
 272 \class{RawConfigParser} interface, adding some optional arguments.
 273
 274 \begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
 275 Get an \var{option} value for the named \var{section}.  All the
 276 \character{\%} interpolations are expanded in the return values, based
 277 on the defaults passed into the constructor, as well as the options
 278 \var{vars} provided, unless the \var{raw} argument is true.
 279 \end{methoddesc}
 280
 281 \begin{methoddesc}{items}{section\optional{, raw\optional{, vars}}}
 282 Create a generator which will return a tuple \code{(name, value)} for
 283 each option in the given \var{section}. Optional arguments have the
 284 same meaning as for the \code{get()} method.
 285 \versionadded{2.3}
 286 \end{methoddesc}