blob: 92e3f9c6af97e94032b04131e1a1c57da946394d [file] [log] [blame]
Fred Drakebc866ce1999-01-26 15:47:59 +00001\section{\module{ConfigParser} ---
Fred Drake4747f7f1999-04-21 16:41:40 +00002 Configuration file parser}
Fred Drakebc866ce1999-01-26 15:47:59 +00003
4\declaremodule{standard}{ConfigParser}
Fred Drakebc866ce1999-01-26 15:47:59 +00005\modulesynopsis{Configuration file parser.}
Fred Drake38e5d272000-04-03 20:13:55 +00006\moduleauthor{Ken Manheimer}{klm@digicool.com}
7\moduleauthor{Barry Warsaw}{bwarsaw@python.org}
Eric S. Raymond417c4892000-07-10 18:11:00 +00008\moduleauthor{Eric S. Raymond}{esr@thyrsus.com}
Fred Drakebc866ce1999-01-26 15:47:59 +00009\sectionauthor{Christopher G. Petrilli}{petrilli@amber.org}
10
Fred Drake1e440291999-06-15 17:30:59 +000011This module defines the class \class{ConfigParser}.
12\indexii{.ini}{file}\indexii{configuration}{file}\index{ini file}
13\index{Windows ini file}
14The \class{ConfigParser} class implements a basic configuration file
Fred Drakebc866ce1999-01-26 15:47:59 +000015parser language which provides a structure similar to what you would
Fred Drake81e4aa72002-12-30 23:50:19 +000016find on Microsoft Windows INI files. You can use this to write Python
Fred Drakebc866ce1999-01-26 15:47:59 +000017programs which can be customized by end users easily.
18
Fred Drake81e4aa72002-12-30 23:50:19 +000019\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
Eric S. Raymond56b31842002-12-27 20:05:36 +000024The configuration file consists of sections, led by a
Fred Drakebc866ce1999-01-26 15:47:59 +000025\samp{[section]} header and followed by \samp{name: value} entries,
Fred Drake1e440291999-06-15 17:30:59 +000026with continuations in the style of \rfc{822}; \samp{name=value} is
Fred Drake38e5d272000-04-03 20:13:55 +000027also accepted. Note that leading whitespace is removed from values.
28The optional values can contain format strings which refer to other
29values in the same section, or values in a special
Fred Drake97d5f052002-10-25 20:20:58 +000030\code{DEFAULT} section. Additional defaults can be provided on
Fred Drake38e5d272000-04-03 20:13:55 +000031initialization and retrieval. Lines beginning with \character{\#} or
32\character{;} are ignored and may be used to provide comments.
Fred Drakebc866ce1999-01-26 15:47:59 +000033
34For example:
35
36\begin{verbatim}
Fred Drake97d5f052002-10-25 20:20:58 +000037[My Section]
Fred Drakebc866ce1999-01-26 15:47:59 +000038foodir: %(dir)s/whatever
Fred Drake38e5d272000-04-03 20:13:55 +000039dir=frob
Fred Drakebc866ce1999-01-26 15:47:59 +000040\end{verbatim}
41
Fred Drake38e5d272000-04-03 20:13:55 +000042would resolve the \samp{\%(dir)s} to the value of
43\samp{dir} (\samp{frob} in this case). All reference expansions are
44done on demand.
Fred Drakebc866ce1999-01-26 15:47:59 +000045
Fred Drake38e5d272000-04-03 20:13:55 +000046Default values can be specified by passing them into the
47\class{ConfigParser} constructor as a dictionary. Additional defaults
48may be passed into the \method{get()} method which will override all
Fred Drakeebe2a121999-01-26 21:49:05 +000049others.
Fred Drakebc866ce1999-01-26 15:47:59 +000050
Fred Drake97d5f052002-10-25 20:20:58 +000051\begin{classdesc}{RawConfigParser}{\optional{defaults}}
52The basic configuration object. When \var{defaults} is given, it is
53initialized into the dictionary of intrinsic defaults. This class
54does not support the magical interpolation behavior.
55\versionadded{2.3}
56\end{classdesc}
57
Fred Drakebc866ce1999-01-26 15:47:59 +000058\begin{classdesc}{ConfigParser}{\optional{defaults}}
Fred Drake97d5f052002-10-25 20:20:58 +000059Derived class of \class{RawConfigParser} that implements the magical
60interpolation feature and adds optional arguments the \method{get()}
61and \method{items()} methods. The values in \var{defaults} must be
Fred Drakebc866ce1999-01-26 15:47:59 +000062appropriate for the \samp{\%()s} string interpolation. Note that
Fred Drake33dde922000-09-27 22:48:44 +000063\var{__name__} is an intrinsic default; its value is the section name,
64and will override any value provided in \var{defaults}.
Fred Drakebc866ce1999-01-26 15:47:59 +000065\end{classdesc}
66
Fred Drake0eebd5c2002-10-25 21:52:00 +000067\begin{classdesc}{SafeConfigParser}{\optional{defaults}}
68Derived class of \class{ConfigParser} that implements a more-sane
69variant of the magical interpolation feature. This implementation is
70more predictable as well.
71% XXX Need to explain what's safer/more predictable about it.
72New applications should prefer this version if they don't need to be
73compatible with older versions of Python.
74\versionadded{2.3}
75\end{classdesc}
76
Fred Drakebc866ce1999-01-26 15:47:59 +000077\begin{excdesc}{NoSectionError}
78Exception raised when a specified section is not found.
79\end{excdesc}
80
81\begin{excdesc}{DuplicateSectionError}
Thomas Woutersf8316632000-07-16 19:01:10 +000082Exception raised when multiple sections with the same name are found,
Fred Drake38e5d272000-04-03 20:13:55 +000083or if \method{add_section()} is called with the name of a section that
84is already present.
Fred Drakebc866ce1999-01-26 15:47:59 +000085\end{excdesc}
86
87\begin{excdesc}{NoOptionError}
88Exception raised when a specified option is not found in the specified
89section.
90\end{excdesc}
91
92\begin{excdesc}{InterpolationError}
93Exception raised when problems occur performing string interpolation.
94\end{excdesc}
95
Fred Drake33dde922000-09-27 22:48:44 +000096\begin{excdesc}{InterpolationDepthError}
97Exception raised when string interpolation cannot be completed because
98the number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}.
99\end{excdesc}
100
Fred Drake81e4aa72002-12-30 23:50:19 +0000101\begin{excdesc}{InterpolationSyntaxError}
102Exception raised when the source text into which substitutions are
103made does not conform to the required syntax.
104\end{excdesc}
105
Fred Drakebc866ce1999-01-26 15:47:59 +0000106\begin{excdesc}{MissingSectionHeaderError}
107Exception raised when attempting to parse a file which has no section
108headers.
109\end{excdesc}
110
111\begin{excdesc}{ParsingError}
112Exception raised when errors occur attempting to parse a file.
113\end{excdesc}
114
Fred Drake33dde922000-09-27 22:48:44 +0000115\begin{datadesc}{MAX_INTERPOLATION_DEPTH}
116The maximum depth for recursive interpolation for \method{get()} when
Fred Drake97d5f052002-10-25 20:20:58 +0000117the \var{raw} parameter is false. This is relevant only for the
118\class{ConfigParser} class.
Fred Drake33dde922000-09-27 22:48:44 +0000119\end{datadesc}
120
Fred Drakeebe2a121999-01-26 21:49:05 +0000121
Fred Drake184e8361999-05-11 15:14:15 +0000122\begin{seealso}
123 \seemodule{shlex}{Support for a creating \UNIX{} shell-like
124 minilanguages which can be used as an alternate format
125 for application configuration files.}
126\end{seealso}
127
Fred Drake5b0705d2001-02-19 22:37:24 +0000128
Fred Drake97d5f052002-10-25 20:20:58 +0000129\subsection{RawConfigParser Objects \label{RawConfigParser-objects}}
Fred Drakebc866ce1999-01-26 15:47:59 +0000130
Fred Drake97d5f052002-10-25 20:20:58 +0000131\class{RawConfigParser} instances have the following methods:
Fred Drakebc866ce1999-01-26 15:47:59 +0000132
133\begin{methoddesc}{defaults}{}
Fred Drake7cb42cd2000-05-23 02:28:26 +0000134Return a dictionary containing the instance-wide defaults.
Fred Drakebc866ce1999-01-26 15:47:59 +0000135\end{methoddesc}
136
137\begin{methoddesc}{sections}{}
Fred Drake38e5d272000-04-03 20:13:55 +0000138Return a list of the sections available; \code{DEFAULT} is not
139included in the list.
140\end{methoddesc}
141
142\begin{methoddesc}{add_section}{section}
143Add a section named \var{section} to the instance. If a section by
144the given name already exists, \exception{DuplicateSectionError} is
145raised.
Fred Drakebc866ce1999-01-26 15:47:59 +0000146\end{methoddesc}
147
148\begin{methoddesc}{has_section}{section}
149Indicates whether the named section is present in the
150configuration. The \code{DEFAULT} section is not acknowledged.
151\end{methoddesc}
152
153\begin{methoddesc}{options}{section}
154Returns a list of options available in the specified \var{section}.
155\end{methoddesc}
156
Eric S. Raymond417c4892000-07-10 18:11:00 +0000157\begin{methoddesc}{has_option}{section, option}
158If the given section exists, and contains the given option. return 1;
Fred Drake3c10c682001-09-28 16:57:16 +0000159otherwise return 0.
160\versionadded{1.6}
Eric S. Raymond417c4892000-07-10 18:11:00 +0000161\end{methoddesc}
162
Fred Drakebc866ce1999-01-26 15:47:59 +0000163\begin{methoddesc}{read}{filenames}
Fred Draked85f0592000-05-09 15:06:32 +0000164Read and parse a list of filenames. If \var{filenames} is a string or
165Unicode string, it is treated as a single filename.
Fred Drake8b7bb7a2001-12-07 21:35:57 +0000166If a file named in \var{filenames} cannot be opened, that file will be
167ignored. This is designed so that you can specify a list of potential
168configuration file locations (for example, the current directory, the
169user's home directory, and some system-wide directory), and all
170existing configuration files in the list will be read. If none of the
171named files exist, the \class{ConfigParser} instance will contain an
172empty dataset. An application which requires initial values to be
173loaded from a file should load the required file or files using
174\method{readfp()} before calling \method{read()} for any optional
175files:
176
177\begin{verbatim}
178import ConfigParser, os
179
180config = ConfigParser.ConfigParser()
181config.readfp(open('defaults.cfg'))
182config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
183\end{verbatim}
Fred Draked85f0592000-05-09 15:06:32 +0000184\end{methoddesc}
185
186\begin{methoddesc}{readfp}{fp\optional{, filename}}
187Read and parse configuration data from the file or file-like object in
188\var{fp} (only the \method{readline()} method is used). If
189\var{filename} is omitted and \var{fp} has a \member{name} attribute,
190that is used for \var{filename}; the default is \samp{<???>}.
Fred Drakebc866ce1999-01-26 15:47:59 +0000191\end{methoddesc}
192
Fred Drake97d5f052002-10-25 20:20:58 +0000193\begin{methoddesc}{get}{section, option}
194Get an \var{option} value for the named \var{section}.
Fred Drakebc866ce1999-01-26 15:47:59 +0000195\end{methoddesc}
196
197\begin{methoddesc}{getint}{section, option}
198A convenience method which coerces the \var{option} in the specified
199\var{section} to an integer.
200\end{methoddesc}
201
202\begin{methoddesc}{getfloat}{section, option}
203A convenience method which coerces the \var{option} in the specified
204\var{section} to a floating point number.
205\end{methoddesc}
206
207\begin{methoddesc}{getboolean}{section, option}
208A convenience method which coerces the \var{option} in the specified
Fred Drakeb35f0ce2001-10-08 16:03:20 +0000209\var{section} to a Boolean value. Note that the accepted values
210for the option are \code{1}, \code{yes}, \code{true}, and \code{on},
211which cause this method to return true, and \code{0}, \code{no},
Fred Drake6959a2f2001-10-09 14:58:24 +0000212\code{false}, and \code{off}, which cause it to return false. These
213values are checked in a case-insensitive manner. Any other value will
214cause it to raise \exception{ValueError}.
Fred Drakebc866ce1999-01-26 15:47:59 +0000215\end{methoddesc}
Eric S. Raymond417c4892000-07-10 18:11:00 +0000216
Fred Drake97d5f052002-10-25 20:20:58 +0000217\begin{methoddesc}{items}{section}
218Return a list of \code{(\var{name}, \var{value})} pairs for each
219option in the given \var{section}.
Fred Drake2ca041f2002-09-27 15:49:56 +0000220\end{methoddesc}
221
Eric S. Raymond417c4892000-07-10 18:11:00 +0000222\begin{methoddesc}{set}{section, option, value}
223If the given section exists, set the given option to the specified value;
Fred Drake3c10c682001-09-28 16:57:16 +0000224otherwise raise \exception{NoSectionError}.
225\versionadded{1.6}
Eric S. Raymond417c4892000-07-10 18:11:00 +0000226\end{methoddesc}
227
Eric S. Raymondf868de62000-07-14 15:00:02 +0000228\begin{methoddesc}{write}{fileobject}
Eric S. Raymond417c4892000-07-10 18:11:00 +0000229Write a representation of the configuration to the specified file
230object. This representation can be parsed by a future \method{read()}
Fred Drake3c10c682001-09-28 16:57:16 +0000231call.
232\versionadded{1.6}
Eric S. Raymond417c4892000-07-10 18:11:00 +0000233\end{methoddesc}
Eric S. Raymondf868de62000-07-14 15:00:02 +0000234
235\begin{methoddesc}{remove_option}{section, option}
236Remove the specified \var{option} from the specified \var{section}.
237If the section does not exist, raise \exception{NoSectionError}.
238If the option existed to be removed, return 1; otherwise return 0.
Fred Drake3c10c682001-09-28 16:57:16 +0000239\versionadded{1.6}
Eric S. Raymondf868de62000-07-14 15:00:02 +0000240\end{methoddesc}
241
242\begin{methoddesc}{remove_section}{section}
243Remove the specified \var{section} from the configuration.
Neal Norwitzd3dab2b2002-04-05 02:21:09 +0000244If the section in fact existed, return \code{True}.
245Otherwise return \code{False}.
Eric S. Raymondf868de62000-07-14 15:00:02 +0000246\end{methoddesc}
247
Fred Drake5b0705d2001-02-19 22:37:24 +0000248\begin{methoddesc}{optionxform}{option}
249Transforms the option name \var{option} as found in an input file or
250as passed in by client code to the form that should be used in the
251internal structures. The default implementation returns a lower-case
252version of \var{option}; subclasses may override this or client code
253can set an attribute of this name on instances to affect this
254behavior. Setting this to \function{str()}, for example, would make
255option names case sensitive.
256\end{methoddesc}
Fred Drake97d5f052002-10-25 20:20:58 +0000257
258
259\subsection{ConfigParser Objects \label{ConfigParser-objects}}
260
261The \class{ConfigParser} class extends some methods of the
262\class{RawConfigParser} interface, adding some optional arguments.
263
264\begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
265Get an \var{option} value for the named \var{section}. All the
266\character{\%} interpolations are expanded in the return values, based
267on the defaults passed into the constructor, as well as the options
268\var{vars} provided, unless the \var{raw} argument is true.
269\end{methoddesc}
270
271\begin{methoddesc}{items}{section\optional{, raw\optional{, vars}}}
272Create a generator which will return a tuple \code{(name, value)} for
273each option in the given \var{section}. Optional arguments have the
274same meaning as for the \code{get()} method.
275\versionadded{2.3}
276\end{methoddesc}