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
|
\section{\module{ConfigParser} ---
Configuration file parser}
\declaremodule{standard}{ConfigParser}
\modulesynopsis{Configuration file parser.}
\moduleauthor{Ken Manheimer}{klm@digicool.com}
\moduleauthor{Barry Warsaw}{bwarsaw@python.org}
\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.
The configuration file consists of sections, lead 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 upon
initialization and retrieval. Lines beginning with \character{\#} or
\character{;} are ignored and may be used to provide comments.
For example:
\begin{verbatim}
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}{ConfigParser}{\optional{defaults}}
Return a new instance of the \class{ConfigParser} class. When
\var{defaults} is given, it is initialized into the dictionairy of
intrinsic defaults. They keys must be strings, and the values must be
appropriate for the \samp{\%()s} string interpolation. Note that
\var{__name__} is always an intrinsic default; its value is the
section name.
\end{classdesc}
\begin{excdesc}{NoSectionError}
Exception raised when a specified section is not found.
\end{excdesc}
\begin{excdesc}{DuplicateSectionError}
Exception raised when mutliple sections with the same name are found,
or 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}
Exception raised when problems occur performing string interpolation.
\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{seealso}
\seemodule{shlex}{Support for a creating \UNIX{} shell-like
minilanguages which can be used as an alternate format
for application configuration files.}
\end{seealso}
\subsection{ConfigParser Objects \label{ConfigParser-objects}}
\class{ConfigParser} instances have the following methods:
\begin{methoddesc}{defaults}{}
Return a dictionairy 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}{read}{filenames}
Read and parse a list of filenames.
\end{methoddesc}
\begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
Get an \var{option} value for the provided \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}{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 only accepted values
for the option are \samp{0} and \samp{1}, any others will raise
\exception{ValueError}.
\end{methoddesc}
|
