Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcfgparser.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 9a243ee354a1
children 73d145bfd8e4
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{ConfigParser} ---
10648
48c33d05367f Markup nits.
Fred Drake <fdrake@acm.org>
parents: 10303
diff changeset
2 Configuration file parser}
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{standard}{ConfigParser}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 \modulesynopsis{Configuration file parser.}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
6 \moduleauthor{Ken Manheimer}{klm@digicool.com}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
7 \moduleauthor{Barry Warsaw}{bwarsaw@python.org}
13521
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
8 \moduleauthor{Eric S. Raymond}{esr@thyrsus.com}
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9 \sectionauthor{Christopher G. Petrilli}{petrilli@amber.org}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10
10988
7a127f1992d1 Several new index entries to make find this easier.
Fred Drake <fdrake@acm.org>
parents: 10844
diff changeset
11 This module defines the class \class{ConfigParser}.
7a127f1992d1 Several new index entries to make find this easier.
Fred Drake <fdrake@acm.org>
parents: 10844
diff changeset
12 \indexii{.ini}{file}\indexii{configuration}{file}\index{ini file}
7a127f1992d1 Several new index entries to make find this easier.
Fred Drake <fdrake@acm.org>
parents: 10844
diff changeset
13 \index{Windows ini file}
7a127f1992d1 Several new index entries to make find this easier.
Fred Drake <fdrake@acm.org>
parents: 10844
diff changeset
14 The \class{ConfigParser} class implements a basic configuration file
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15 parser language which provides a structure similar to what you would
10988
7a127f1992d1 Several new index entries to make find this easier.
Fred Drake <fdrake@acm.org>
parents: 10844
diff changeset
16 find on Microsoft Windows INI files. You can use this to write Python
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17 programs which can be customized by end users easily.
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19 The configuration file consists of sections, lead by a
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20 \samp{[section]} header and followed by \samp{name: value} entries,
10988
7a127f1992d1 Several new index entries to make find this easier.
Fred Drake <fdrake@acm.org>
parents: 10844
diff changeset
21 with continuations in the style of \rfc{822}; \samp{name=value} is
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
22 also accepted. Note that leading whitespace is removed from values.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
23 The optional values can contain format strings which refer to other
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
24 values in the same section, or values in a special
10988
7a127f1992d1 Several new index entries to make find this easier.
Fred Drake <fdrake@acm.org>
parents: 10844
diff changeset
25 \code{DEFAULT} section. Additional defaults can be provided upon
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
26 initialization and retrieval. Lines beginning with \character{\#} or
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
27 \character{;} are ignored and may be used to provide comments.
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 For example:
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 \begin{verbatim}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32 foodir: %(dir)s/whatever
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
33 dir=frob
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34 \end{verbatim}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
36 would resolve the \samp{\%(dir)s} to the value of
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
37 \samp{dir} (\samp{frob} in this case). All reference expansions are
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
38 done on demand.
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
40 Default values can be specified by passing them into the
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
41 \class{ConfigParser} constructor as a dictionary. Additional defaults
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
42 may be passed into the \method{get()} method which will override all
9960
92a25d51ff26 Incorporate changes for patched version of ConfigParser.
Fred Drake <fdrake@acm.org>
parents: 9957
diff changeset
43 others.
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45 \begin{classdesc}{ConfigParser}{\optional{defaults}}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 Return a new instance of the \class{ConfigParser} class. When
12731
4118f002e737 From Greg Ward <gward@python.net>:
Fred Drake <fdrake@acm.org>
parents: 12636
diff changeset
47 \var{defaults} is given, it is initialized into the dictionary of
15491
58b4ae4ec55c Typo caught by Jim Tittsler <jwt@onjapan.net>: They --> The
Fred Drake <fdrake@acm.org>
parents: 14901
diff changeset
48 intrinsic defaults. The keys must be strings, and the values must be
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 appropriate for the \samp{\%()s} string interpolation. Note that
14901
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
50 \var{__name__} is an intrinsic default; its value is the section name,
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
51 and will override any value provided in \var{defaults}.
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 \end{classdesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 \begin{excdesc}{NoSectionError}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 Exception raised when a specified section is not found.
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 \end{excdesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 \begin{excdesc}{DuplicateSectionError}
13625
fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents: 13602
diff changeset
59 Exception raised when multiple sections with the same name are found,
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
60 or if \method{add_section()} is called with the name of a section that
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
61 is already present.
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62 \end{excdesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 \begin{excdesc}{NoOptionError}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 Exception raised when a specified option is not found in the specified
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 section.
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 \end{excdesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 \begin{excdesc}{InterpolationError}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70 Exception raised when problems occur performing string interpolation.
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 \end{excdesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72
14901
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
73 \begin{excdesc}{InterpolationDepthError}
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
74 Exception raised when string interpolation cannot be completed because
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
75 the number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}.
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
76 \end{excdesc}
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
77
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 \begin{excdesc}{MissingSectionHeaderError}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 Exception raised when attempting to parse a file which has no section
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 headers.
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 \end{excdesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83 \begin{excdesc}{ParsingError}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 Exception raised when errors occur attempting to parse a file.
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85 \end{excdesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86
14901
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
87 \begin{datadesc}{MAX_INTERPOLATION_DEPTH}
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
88 The maximum depth for recursive interpolation for \method{get()} when
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
89 the \var{raw} parameter is false. Setting this does not change the
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
90 allowed recursion depth.
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
91 \end{datadesc}
291abebea55b Update the documentation for ConfigParser to match the recent changes.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
92
9960
92a25d51ff26 Incorporate changes for patched version of ConfigParser.
Fred Drake <fdrake@acm.org>
parents: 9957
diff changeset
93
10844
cdf7ae5b3367 Added module references; minor grammatical fixes.
Fred Drake <fdrake@acm.org>
parents: 10648
diff changeset
94 \begin{seealso}
cdf7ae5b3367 Added module references; minor grammatical fixes.
Fred Drake <fdrake@acm.org>
parents: 10648
diff changeset
95 \seemodule{shlex}{Support for a creating \UNIX{} shell-like
cdf7ae5b3367 Added module references; minor grammatical fixes.
Fred Drake <fdrake@acm.org>
parents: 10648
diff changeset
96 minilanguages which can be used as an alternate format
cdf7ae5b3367 Added module references; minor grammatical fixes.
Fred Drake <fdrake@acm.org>
parents: 10648
diff changeset
97 for application configuration files.}
cdf7ae5b3367 Added module references; minor grammatical fixes.
Fred Drake <fdrake@acm.org>
parents: 10648
diff changeset
98 \end{seealso}
cdf7ae5b3367 Added module references; minor grammatical fixes.
Fred Drake <fdrake@acm.org>
parents: 10648
diff changeset
99
16698
1b400c854a2c ConfigParser.optionxform(): Document this since it is available for
Fred Drake <fdrake@acm.org>
parents: 15491
diff changeset
100
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
101 \subsection{ConfigParser Objects \label{ConfigParser-objects}}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
102
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 \class{ConfigParser} instances have the following methods:
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
105 \begin{methoddesc}{defaults}{}
12731
4118f002e737 From Greg Ward <gward@python.net>:
Fred Drake <fdrake@acm.org>
parents: 12636
diff changeset
106 Return a dictionary containing the instance-wide defaults.
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 \end{methoddesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 \begin{methoddesc}{sections}{}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
110 Return a list of the sections available; \code{DEFAULT} is not
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
111 included in the list.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
112 \end{methoddesc}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
113
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
114 \begin{methoddesc}{add_section}{section}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
115 Add a section named \var{section} to the instance. If a section by
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
116 the given name already exists, \exception{DuplicateSectionError} is
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10988
diff changeset
117 raised.
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118 \end{methoddesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 \begin{methoddesc}{has_section}{section}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121 Indicates whether the named section is present in the
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 configuration. The \code{DEFAULT} section is not acknowledged.
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123 \end{methoddesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 \begin{methoddesc}{options}{section}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126 Returns a list of options available in the specified \var{section}.
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 \end{methoddesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128
13521
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
129 \begin{methoddesc}{has_option}{section, option}
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
130 If the given section exists, and contains the given option. return 1;
20147
88da38a5f0bf Use consistent version annotations instead of something ad hoc.
Fred Drake <fdrake@acm.org>
parents: 16698
diff changeset
131 otherwise return 0.
88da38a5f0bf Use consistent version annotations instead of something ad hoc.
Fred Drake <fdrake@acm.org>
parents: 16698
diff changeset
132 \versionadded{1.6}
13521
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
133 \end{methoddesc}
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
134
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
135 \begin{methoddesc}{read}{filenames}
12636
75da9d63531d read() method: clarify that strings are accepted and interpreted
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
136 Read and parse a list of filenames. If \var{filenames} is a string or
75da9d63531d read() method: clarify that strings are accepted and interpreted
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
137 Unicode string, it is treated as a single filename.
21298
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
138 If a file named in \var{filenames} cannot be opened, that file will be
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
139 ignored. This is designed so that you can specify a list of potential
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
140 configuration file locations (for example, the current directory, the
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
141 user's home directory, and some system-wide directory), and all
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
142 existing configuration files in the list will be read. If none of the
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
143 named files exist, the \class{ConfigParser} instance will contain an
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
144 empty dataset. An application which requires initial values to be
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
145 loaded from a file should load the required file or files using
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
146 \method{readfp()} before calling \method{read()} for any optional
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
147 files:
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
148
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
149 \begin{verbatim}
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
150 import ConfigParser, os
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
151
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
152 config = ConfigParser.ConfigParser()
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
153 config.readfp(open('defaults.cfg'))
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
154 config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
9a243ee354a1 Describe the behavior of the read() method when the list of filenames
Fred Drake <fdrake@acm.org>
parents: 20331
diff changeset
155 \end{verbatim}
12636
75da9d63531d read() method: clarify that strings are accepted and interpreted
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
156 \end{methoddesc}
75da9d63531d read() method: clarify that strings are accepted and interpreted
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
157
75da9d63531d read() method: clarify that strings are accepted and interpreted
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
158 \begin{methoddesc}{readfp}{fp\optional{, filename}}
75da9d63531d read() method: clarify that strings are accepted and interpreted
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
159 Read and parse configuration data from the file or file-like object in
75da9d63531d read() method: clarify that strings are accepted and interpreted
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
160 \var{fp} (only the \method{readline()} method is used). If
75da9d63531d read() method: clarify that strings are accepted and interpreted
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
161 \var{filename} is omitted and \var{fp} has a \member{name} attribute,
75da9d63531d read() method: clarify that strings are accepted and interpreted
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
162 that is used for \var{filename}; the default is \samp{<???>}.
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
163 \end{methoddesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164
9960
92a25d51ff26 Incorporate changes for patched version of ConfigParser.
Fred Drake <fdrake@acm.org>
parents: 9957
diff changeset
165 \begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
166 Get an \var{option} value for the provided \var{section}. All the
10648
48c33d05367f Markup nits.
Fred Drake <fdrake@acm.org>
parents: 10303
diff changeset
167 \character{\%} interpolations are expanded in the return values, based on
9960
92a25d51ff26 Incorporate changes for patched version of ConfigParser.
Fred Drake <fdrake@acm.org>
parents: 9957
diff changeset
168 the defaults passed into the constructor, as well as the options
92a25d51ff26 Incorporate changes for patched version of ConfigParser.
Fred Drake <fdrake@acm.org>
parents: 9957
diff changeset
169 \var{vars} provided, unless the \var{raw} argument is true.
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170 \end{methoddesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172 \begin{methoddesc}{getint}{section, option}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173 A convenience method which coerces the \var{option} in the specified
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174 \var{section} to an integer.
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 \end{methoddesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
176
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
177 \begin{methoddesc}{getfloat}{section, option}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
178 A convenience method which coerces the \var{option} in the specified
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
179 \var{section} to a floating point number.
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180 \end{methoddesc}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
181
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
182 \begin{methoddesc}{getboolean}{section, option}
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
183 A convenience method which coerces the \var{option} in the specified
20318
f9a66b24bfff Update the description of getboolean() to reflect the changes made by
Fred Drake <fdrake@acm.org>
parents: 20202
diff changeset
184 \var{section} to a Boolean value. Note that the accepted values
f9a66b24bfff Update the description of getboolean() to reflect the changes made by
Fred Drake <fdrake@acm.org>
parents: 20202
diff changeset
185 for the option are \code{1}, \code{yes}, \code{true}, and \code{on},
f9a66b24bfff Update the description of getboolean() to reflect the changes made by
Fred Drake <fdrake@acm.org>
parents: 20202
diff changeset
186 which cause this method to return true, and \code{0}, \code{no},
20331
c5247a366ff5 Note that the values for Boolean options are case-insensitive.
Fred Drake <fdrake@acm.org>
parents: 20318
diff changeset
187 \code{false}, and \code{off}, which cause it to return false. These
c5247a366ff5 Note that the values for Boolean options are case-insensitive.
Fred Drake <fdrake@acm.org>
parents: 20318
diff changeset
188 values are checked in a case-insensitive manner. Any other value will
c5247a366ff5 Note that the values for Boolean options are case-insensitive.
Fred Drake <fdrake@acm.org>
parents: 20318
diff changeset
189 cause it to raise \exception{ValueError}.
9957
57bcc6ec638f Documentation for the ConfigParser module, by Christopher G. Petrilli
Fred Drake <fdrake@acm.org>
parents:
diff changeset
190 \end{methoddesc}
13521
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
191
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
192 \begin{methoddesc}{set}{section, option, value}
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
193 If the given section exists, set the given option to the specified value;
20147
88da38a5f0bf Use consistent version annotations instead of something ad hoc.
Fred Drake <fdrake@acm.org>
parents: 16698
diff changeset
194 otherwise raise \exception{NoSectionError}.
88da38a5f0bf Use consistent version annotations instead of something ad hoc.
Fred Drake <fdrake@acm.org>
parents: 16698
diff changeset
195 \versionadded{1.6}
13521
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
196 \end{methoddesc}
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
197
13602
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
198 \begin{methoddesc}{write}{fileobject}
13521
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
199 Write a representation of the configuration to the specified file
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
200 object. This representation can be parsed by a future \method{read()}
20147
88da38a5f0bf Use consistent version annotations instead of something ad hoc.
Fred Drake <fdrake@acm.org>
parents: 16698
diff changeset
201 call.
88da38a5f0bf Use consistent version annotations instead of something ad hoc.
Fred Drake <fdrake@acm.org>
parents: 16698
diff changeset
202 \versionadded{1.6}
13521
4dbc75c189bc Give ConfigParser the capability to set as well as read options, and to write
Eric S. Raymond <esr@thyrsus.com>
parents: 12731
diff changeset
203 \end{methoddesc}
13602
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
204
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
205 \begin{methoddesc}{remove_option}{section, option}
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
206 Remove the specified \var{option} from the specified \var{section}.
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
207 If the section does not exist, raise \exception{NoSectionError}.
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
208 If the option existed to be removed, return 1; otherwise return 0.
20147
88da38a5f0bf Use consistent version annotations instead of something ad hoc.
Fred Drake <fdrake@acm.org>
parents: 16698
diff changeset
209 \versionadded{1.6}
13602
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
210 \end{methoddesc}
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
211
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
212 \begin{methoddesc}{remove_section}{section}
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
213 Remove the specified \var{section} from the configuration.
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
214 If the section in fact existed, return 1. Otherwise return 0.
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
215 \end{methoddesc}
d7aec17cd0b5 Document the second round of ConfigParser changes.
Eric S. Raymond <esr@thyrsus.com>
parents: 13521
diff changeset
216
16698
1b400c854a2c ConfigParser.optionxform(): Document this since it is available for
Fred Drake <fdrake@acm.org>
parents: 15491
diff changeset
217 \begin{methoddesc}{optionxform}{option}
1b400c854a2c ConfigParser.optionxform(): Document this since it is available for
Fred Drake <fdrake@acm.org>
parents: 15491
diff changeset
218 Transforms the option name \var{option} as found in an input file or
1b400c854a2c ConfigParser.optionxform(): Document this since it is available for
Fred Drake <fdrake@acm.org>
parents: 15491
diff changeset
219 as passed in by client code to the form that should be used in the
1b400c854a2c ConfigParser.optionxform(): Document this since it is available for
Fred Drake <fdrake@acm.org>
parents: 15491
diff changeset
220 internal structures. The default implementation returns a lower-case
1b400c854a2c ConfigParser.optionxform(): Document this since it is available for
Fred Drake <fdrake@acm.org>
parents: 15491
diff changeset
221 version of \var{option}; subclasses may override this or client code
1b400c854a2c ConfigParser.optionxform(): Document this since it is available for
Fred Drake <fdrake@acm.org>
parents: 15491
diff changeset
222 can set an attribute of this name on instances to affect this
1b400c854a2c ConfigParser.optionxform(): Document this since it is available for
Fred Drake <fdrake@acm.org>
parents: 15491
diff changeset
223 behavior. Setting this to \function{str()}, for example, would make
1b400c854a2c ConfigParser.optionxform(): Document this since it is available for
Fred Drake <fdrake@acm.org>
parents: 15491
diff changeset
224 option names case sensitive.
1b400c854a2c ConfigParser.optionxform(): Document this since it is available for
Fred Drake <fdrake@acm.org>
parents: 15491
diff changeset
225 \end{methoddesc}