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 The configuration file consists of sections, lead by a
  20 \samp{[section]} header and followed by \samp{name: value} entries,
  21 with continuations in the style of \rfc{822}; \samp{name=value} is
  22 also accepted.  Note that leading whitespace is removed from values.
  23 The optional values can contain format strings which refer to other
  24 values in the same section, or values in a special
  25 \code{DEFAULT} section.  Additional defaults can be provided upon
  26 initialization and retrieval.  Lines beginning with \character{\#} or
  27 \character{;} are ignored and may be used to provide comments.
  28
  29 For example:
  30
  31 \begin{verbatim}
  32 foodir: %(dir)s/whatever
  33 dir=frob
  34 \end{verbatim}
  35
  36 would resolve the \samp{\%(dir)s} to the value of
  37 \samp{dir} (\samp{frob} in this case).  All reference expansions are
  38 done on demand.
  39
  40 Default values can be specified by passing them into the
  41 \class{ConfigParser} constructor as a dictionary.  Additional defaults
  42 may be passed into the \method{get()} method which will override all
  43 others.
  44
  45 \begin{classdesc}{ConfigParser}{\optional{defaults}}
  46 Return a new instance of the \class{ConfigParser} class.  When
  47 \var{defaults} is given, it is initialized into the dictionary of
  48 intrinsic defaults.  The keys must be strings, and the values must be
  49 appropriate for the \samp{\%()s} string interpolation.  Note that
  50 \var{__name__} is an intrinsic default; its value is the section name,
  51 and will override any value provided in \var{defaults}.
  52 \end{classdesc}
  53
  54 \begin{excdesc}{NoSectionError}
  55 Exception raised when a specified section is not found.
  56 \end{excdesc}
  57
  58 \begin{excdesc}{DuplicateSectionError}
  59 Exception raised when multiple sections with the same name are found,
  60 or if \method{add_section()} is called with the name of a section that
  61 is already present.
  62 \end{excdesc}
  63
  64 \begin{excdesc}{NoOptionError}
  65 Exception raised when a specified option is not found in the specified
  66 section.
  67 \end{excdesc}
  68
  69 \begin{excdesc}{InterpolationError}
  70 Exception raised when problems occur performing string interpolation.
  71 \end{excdesc}
  72
  73 \begin{excdesc}{InterpolationDepthError}
  74 Exception raised when string interpolation cannot be completed because
  75 the number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}.
  76 \end{excdesc}
  77
  78 \begin{excdesc}{MissingSectionHeaderError}
  79 Exception raised when attempting to parse a file which has no section
  80 headers.
  81 \end{excdesc}
  82
  83 \begin{excdesc}{ParsingError}
  84 Exception raised when errors occur attempting to parse a file.
  85 \end{excdesc}
  86
  87 \begin{datadesc}{MAX_INTERPOLATION_DEPTH}
  88 The maximum depth for recursive interpolation for \method{get()} when
  89 the \var{raw} parameter is false.  Setting this does not change the
  90 allowed recursion depth.
  91 \end{datadesc}
  92
  93
  94 \begin{seealso}
  95   \seemodule{shlex}{Support for a creating \UNIX{} shell-like
  96                     minilanguages which can be used as an alternate format
  97                     for application configuration files.}
  98 \end{seealso}
  99
 100
 101 \subsection{ConfigParser Objects \label{ConfigParser-objects}}
 102
 103 \class{ConfigParser} instances have the following methods:
 104
 105 \begin{methoddesc}{defaults}{}
 106 Return a dictionary containing the instance-wide defaults.
 107 \end{methoddesc}
 108
 109 \begin{methoddesc}{sections}{}
 110 Return a list of the sections available; \code{DEFAULT} is not
 111 included in the list.
 112 \end{methoddesc}
 113
 114 \begin{methoddesc}{add_section}{section}
 115 Add a section named \var{section} to the instance.  If a section by
 116 the given name already exists, \exception{DuplicateSectionError} is
 117 raised.
 118 \end{methoddesc}
 119
 120 \begin{methoddesc}{has_section}{section}
 121 Indicates whether the named section is present in the
 122 configuration. The \code{DEFAULT} section is not acknowledged.
 123 \end{methoddesc}
 124
 125 \begin{methoddesc}{options}{section}
 126 Returns a list of options available in the specified \var{section}.
 127 \end{methoddesc}
 128
 129 \begin{methoddesc}{has_option}{section, option}
 130 If the given section exists, and contains the given option. return 1;
 131 otherwise return 0.
 132 \versionadded{1.6}
 133 \end{methoddesc}
 134
 135 \begin{methoddesc}{read}{filenames}
 136 Read and parse a list of filenames.  If \var{filenames} is a string or
 137 Unicode string, it is treated as a single filename.
 138 If a file named in \var{filenames} cannot be opened, that file will be
 139 ignored.  This is designed so that you can specify a list of potential
 140 configuration file locations (for example, the current directory, the
 141 user's home directory, and some system-wide directory), and all
 142 existing configuration files in the list will be read.  If none of the
 143 named files exist, the \class{ConfigParser} instance will contain an
 144 empty dataset.  An application which requires initial values to be
 145 loaded from a file should load the required file or files using
 146 \method{readfp()} before calling \method{read()} for any optional
 147 files:
 148
 149 \begin{verbatim}
 150 import ConfigParser, os
 151
 152 config = ConfigParser.ConfigParser()
 153 config.readfp(open('defaults.cfg'))
 154 config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
 155 \end{verbatim}
 156 \end{methoddesc}
 157
 158 \begin{methoddesc}{readfp}{fp\optional{, filename}}
 159 Read and parse configuration data from the file or file-like object in
 160 \var{fp} (only the \method{readline()} method is used).  If
 161 \var{filename} is omitted and \var{fp} has a \member{name} attribute,
 162 that is used for \var{filename}; the default is \samp{<???>}.
 163 \end{methoddesc}
 164
 165 \begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
 166 Get an \var{option} value for the provided \var{section}.  All the
 167 \character{\%} interpolations are expanded in the return values, based on
 168 the defaults passed into the constructor, as well as the options
 169 \var{vars} provided, unless the \var{raw} argument is true.
 170 \end{methoddesc}
 171
 172 \begin{methoddesc}{getint}{section, option}
 173 A convenience method which coerces the \var{option} in the specified
 174 \var{section} to an integer.
 175 \end{methoddesc}
 176
 177 \begin{methoddesc}{getfloat}{section, option}
 178 A convenience method which coerces the \var{option} in the specified
 179 \var{section} to a floating point number.
 180 \end{methoddesc}
 181
 182 \begin{methoddesc}{getboolean}{section, option}
 183 A convenience method which coerces the \var{option} in the specified
 184 \var{section} to a Boolean value.  Note that the accepted values
 185 for the option are \code{1}, \code{yes}, \code{true}, and \code{on},
 186 which cause this method to return true, and \code{0}, \code{no},
 187 \code{false}, and \code{off}, which cause it to return false.  These
 188 values are checked in a case-insensitive manner.  Any other value will
 189 cause it to raise \exception{ValueError}.
 190 \end{methoddesc}
 191
 192 \begin{methoddesc}{items}{section\optional{, raw\optional{, vars}}}
 193 Create a generator which will return a tuple \code{(name, value)} for
 194 each option in the given \var{section}. Optional arguments have the
 195 same meaning as for the \code{get()} method.
 196 \versionadded{2.3}
 197 \end{methoddesc}
 198
 199 \begin{methoddesc}{set}{section, option, value}
 200 If the given section exists, set the given option to the specified value;
 201 otherwise raise \exception{NoSectionError}.
 202 \versionadded{1.6}
 203 \end{methoddesc}
 204
 205 \begin{methoddesc}{write}{fileobject}
 206 Write a representation of the configuration to the specified file
 207 object.  This representation can be parsed by a future \method{read()}
 208 call.
 209 \versionadded{1.6}
 210 \end{methoddesc}
 211
 212 \begin{methoddesc}{remove_option}{section, option}
 213 Remove the specified \var{option} from the specified \var{section}.
 214 If the section does not exist, raise \exception{NoSectionError}.
 215 If the option existed to be removed, return 1; otherwise return 0.
 216 \versionadded{1.6}
 217 \end{methoddesc}
 218
 219 \begin{methoddesc}{remove_section}{section}
 220 Remove the specified \var{section} from the configuration.
 221 If the section in fact existed, return \code{True}.
 222 Otherwise return \code{False}.
 223 \end{methoddesc}
 224
 225 \begin{methoddesc}{optionxform}{option}
 226 Transforms the option name \var{option} as found in an input file or
 227 as passed in by  client code to the form that should be used in the
 228 internal structures.  The default implementation returns a lower-case
 229 version of \var{option}; subclasses may override this or client code
 230 can set an attribute of this name on instances to affect this
 231 behavior.  Setting this to \function{str()}, for example, would make
 232 option names case sensitive.
 233 \end{methoddesc}