blob: ff01fdefb35a4255d47834b0209bd73e5e299f39 [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 Drake1e440291999-06-15 17:30:59 +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
19The configuration file consists of sections, lead by a
20\samp{[section]} header and followed by \samp{name: value} entries,
Fred Drake1e440291999-06-15 17:30:59 +000021with continuations in the style of \rfc{822}; \samp{name=value} is
Fred Drake38e5d272000-04-03 20:13:55 +000022also accepted. Note that leading whitespace is removed from values.
23The optional values can contain format strings which refer to other
24values in the same section, or values in a special
Fred Drake1e440291999-06-15 17:30:59 +000025\code{DEFAULT} section. Additional defaults can be provided upon
Fred Drake38e5d272000-04-03 20:13:55 +000026initialization and retrieval. Lines beginning with \character{\#} or
27\character{;} are ignored and may be used to provide comments.
Fred Drakebc866ce1999-01-26 15:47:59 +000028
29For example:
30
31\begin{verbatim}
32foodir: %(dir)s/whatever
Fred Drake38e5d272000-04-03 20:13:55 +000033dir=frob
Fred Drakebc866ce1999-01-26 15:47:59 +000034\end{verbatim}
35
Fred Drake38e5d272000-04-03 20:13:55 +000036would resolve the \samp{\%(dir)s} to the value of
37\samp{dir} (\samp{frob} in this case). All reference expansions are
38done on demand.
Fred Drakebc866ce1999-01-26 15:47:59 +000039
Fred Drake38e5d272000-04-03 20:13:55 +000040Default values can be specified by passing them into the
41\class{ConfigParser} constructor as a dictionary. Additional defaults
42may be passed into the \method{get()} method which will override all
Fred Drakeebe2a121999-01-26 21:49:05 +000043others.
Fred Drakebc866ce1999-01-26 15:47:59 +000044
45\begin{classdesc}{ConfigParser}{\optional{defaults}}
46Return a new instance of the \class{ConfigParser} class. When
Fred Drake7cb42cd2000-05-23 02:28:26 +000047\var{defaults} is given, it is initialized into the dictionary of
Fred Drakefd4d29c2000-12-07 00:03:24 +000048intrinsic defaults. The keys must be strings, and the values must be
Fred Drakebc866ce1999-01-26 15:47:59 +000049appropriate for the \samp{\%()s} string interpolation. Note that
Fred Drake33dde922000-09-27 22:48:44 +000050\var{__name__} is an intrinsic default; its value is the section name,
51and will override any value provided in \var{defaults}.
Fred Drakebc866ce1999-01-26 15:47:59 +000052\end{classdesc}
53
54\begin{excdesc}{NoSectionError}
55Exception raised when a specified section is not found.
56\end{excdesc}
57
58\begin{excdesc}{DuplicateSectionError}
Thomas Woutersf8316632000-07-16 19:01:10 +000059Exception raised when multiple sections with the same name are found,
Fred Drake38e5d272000-04-03 20:13:55 +000060or if \method{add_section()} is called with the name of a section that
61is already present.
Fred Drakebc866ce1999-01-26 15:47:59 +000062\end{excdesc}
63
64\begin{excdesc}{NoOptionError}
65Exception raised when a specified option is not found in the specified
66section.
67\end{excdesc}
68
69\begin{excdesc}{InterpolationError}
70Exception raised when problems occur performing string interpolation.
71\end{excdesc}
72
Fred Drake33dde922000-09-27 22:48:44 +000073\begin{excdesc}{InterpolationDepthError}
74Exception raised when string interpolation cannot be completed because
75the number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}.
76\end{excdesc}
77
Fred Drakebc866ce1999-01-26 15:47:59 +000078\begin{excdesc}{MissingSectionHeaderError}
79Exception raised when attempting to parse a file which has no section
80headers.
81\end{excdesc}
82
83\begin{excdesc}{ParsingError}
84Exception raised when errors occur attempting to parse a file.
85\end{excdesc}
86
Fred Drake33dde922000-09-27 22:48:44 +000087\begin{datadesc}{MAX_INTERPOLATION_DEPTH}
88The maximum depth for recursive interpolation for \method{get()} when
89the \var{raw} parameter is false. Setting this does not change the
90allowed recursion depth.
91\end{datadesc}
92
Fred Drakeebe2a121999-01-26 21:49:05 +000093
Fred Drake184e8361999-05-11 15:14:15 +000094\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
Fred Drake5b0705d2001-02-19 22:37:24 +0000100
Fred Drakebc866ce1999-01-26 15:47:59 +0000101\subsection{ConfigParser Objects \label{ConfigParser-objects}}
102
103\class{ConfigParser} instances have the following methods:
104
105\begin{methoddesc}{defaults}{}
Fred Drake7cb42cd2000-05-23 02:28:26 +0000106Return a dictionary containing the instance-wide defaults.
Fred Drakebc866ce1999-01-26 15:47:59 +0000107\end{methoddesc}
108
109\begin{methoddesc}{sections}{}
Fred Drake38e5d272000-04-03 20:13:55 +0000110Return a list of the sections available; \code{DEFAULT} is not
111included in the list.
112\end{methoddesc}
113
114\begin{methoddesc}{add_section}{section}
115Add a section named \var{section} to the instance. If a section by
116the given name already exists, \exception{DuplicateSectionError} is
117raised.
Fred Drakebc866ce1999-01-26 15:47:59 +0000118\end{methoddesc}
119
120\begin{methoddesc}{has_section}{section}
121Indicates whether the named section is present in the
122configuration. The \code{DEFAULT} section is not acknowledged.
123\end{methoddesc}
124
125\begin{methoddesc}{options}{section}
126Returns a list of options available in the specified \var{section}.
127\end{methoddesc}
128
Eric S. Raymond417c4892000-07-10 18:11:00 +0000129\begin{methoddesc}{has_option}{section, option}
130If the given section exists, and contains the given option. return 1;
Fred Drake3c10c682001-09-28 16:57:16 +0000131otherwise return 0.
132\versionadded{1.6}
Eric S. Raymond417c4892000-07-10 18:11:00 +0000133\end{methoddesc}
134
Fred Drakebc866ce1999-01-26 15:47:59 +0000135\begin{methoddesc}{read}{filenames}
Fred Draked85f0592000-05-09 15:06:32 +0000136Read and parse a list of filenames. If \var{filenames} is a string or
137Unicode string, it is treated as a single filename.
Fred Drake8b7bb7a2001-12-07 21:35:57 +0000138If a file named in \var{filenames} cannot be opened, that file will be
139ignored. This is designed so that you can specify a list of potential
140configuration file locations (for example, the current directory, the
141user's home directory, and some system-wide directory), and all
142existing configuration files in the list will be read. If none of the
143named files exist, the \class{ConfigParser} instance will contain an
144empty dataset. An application which requires initial values to be
145loaded from a file should load the required file or files using
146\method{readfp()} before calling \method{read()} for any optional
147files:
148
149\begin{verbatim}
150import ConfigParser, os
151
152config = ConfigParser.ConfigParser()
153config.readfp(open('defaults.cfg'))
154config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
155\end{verbatim}
Fred Draked85f0592000-05-09 15:06:32 +0000156\end{methoddesc}
157
158\begin{methoddesc}{readfp}{fp\optional{, filename}}
159Read 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,
162that is used for \var{filename}; the default is \samp{<???>}.
Fred Drakebc866ce1999-01-26 15:47:59 +0000163\end{methoddesc}
164
Fred Drakeebe2a121999-01-26 21:49:05 +0000165\begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
Fred Drakebc866ce1999-01-26 15:47:59 +0000166Get an \var{option} value for the provided \var{section}. All the
Fred Drake4747f7f1999-04-21 16:41:40 +0000167\character{\%} interpolations are expanded in the return values, based on
Fred Drakeebe2a121999-01-26 21:49:05 +0000168the defaults passed into the constructor, as well as the options
169\var{vars} provided, unless the \var{raw} argument is true.
Fred Drakebc866ce1999-01-26 15:47:59 +0000170\end{methoddesc}
171
172\begin{methoddesc}{getint}{section, option}
173A 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}
178A 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}
183A convenience method which coerces the \var{option} in the specified
Fred Drakeb35f0ce2001-10-08 16:03:20 +0000184\var{section} to a Boolean value. Note that the accepted values
185for the option are \code{1}, \code{yes}, \code{true}, and \code{on},
186which cause this method to return true, and \code{0}, \code{no},
Fred Drake6959a2f2001-10-09 14:58:24 +0000187\code{false}, and \code{off}, which cause it to return false. These
188values are checked in a case-insensitive manner. Any other value will
189cause it to raise \exception{ValueError}.
Fred Drakebc866ce1999-01-26 15:47:59 +0000190\end{methoddesc}
Eric S. Raymond417c4892000-07-10 18:11:00 +0000191
192\begin{methoddesc}{set}{section, option, value}
193If the given section exists, set the given option to the specified value;
Fred Drake3c10c682001-09-28 16:57:16 +0000194otherwise raise \exception{NoSectionError}.
195\versionadded{1.6}
Eric S. Raymond417c4892000-07-10 18:11:00 +0000196\end{methoddesc}
197
Eric S. Raymondf868de62000-07-14 15:00:02 +0000198\begin{methoddesc}{write}{fileobject}
Eric S. Raymond417c4892000-07-10 18:11:00 +0000199Write a representation of the configuration to the specified file
200object. This representation can be parsed by a future \method{read()}
Fred Drake3c10c682001-09-28 16:57:16 +0000201call.
202\versionadded{1.6}
Eric S. Raymond417c4892000-07-10 18:11:00 +0000203\end{methoddesc}
Eric S. Raymondf868de62000-07-14 15:00:02 +0000204
205\begin{methoddesc}{remove_option}{section, option}
206Remove the specified \var{option} from the specified \var{section}.
207If the section does not exist, raise \exception{NoSectionError}.
208If the option existed to be removed, return 1; otherwise return 0.
Fred Drake3c10c682001-09-28 16:57:16 +0000209\versionadded{1.6}
Eric S. Raymondf868de62000-07-14 15:00:02 +0000210\end{methoddesc}
211
212\begin{methoddesc}{remove_section}{section}
213Remove the specified \var{section} from the configuration.
214If the section in fact existed, return 1. Otherwise return 0.
215\end{methoddesc}
216
Fred Drake5b0705d2001-02-19 22:37:24 +0000217\begin{methoddesc}{optionxform}{option}
218Transforms the option name \var{option} as found in an input file or
219as passed in by client code to the form that should be used in the
220internal structures. The default implementation returns a lower-case
221version of \var{option}; subclasses may override this or client code
222can set an attribute of this name on instances to affect this
223behavior. Setting this to \function{str()}, for example, would make
224option names case sensitive.
225\end{methoddesc}