cpython-lru_cache-weakref: Doc/library/configparser.rst annotate

annotate Doc/library/configparser.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	1ee270d522f3
children

rev	line source
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	1 :mod:`ConfigParser` --- Configuration file parser
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 =================================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
47010 7e18d6593824 Added documentation stub for ConfigParser. Alexandre Vassalotti <alexandre@peadrop.com> parents: 47009 diff changeset	4 .. module:: ConfigParser
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 :synopsis: Configuration file parser.
47009 708214f351fe Updated import statements to use the new `configparser` module name. Alexandre Vassalotti <alexandre@peadrop.com> parents: 47008 diff changeset	6
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 .. moduleauthor:: Ken Manheimer <klm@zope.com>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 .. moduleauthor:: Barry Warsaw <bwarsaw@python.org>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 .. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 .. sectionauthor:: Christopher G. Petrilli <petrilli@amber.org>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11
47010 7e18d6593824 Added documentation stub for ConfigParser. Alexandre Vassalotti <alexandre@peadrop.com> parents: 47009 diff changeset	12 .. note::
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	13
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 47252 diff changeset	14 The :mod:`ConfigParser` module has been renamed to :mod:`configparser` in
76732 8aab13719c02 Use Python 3 instead of 3.0. Ezio Melotti <ezio.melotti@gmail.com> parents: 70304 diff changeset	15 Python 3. The :term:`2to3` tool will automatically adapt imports when
8aab13719c02 Use Python 3 instead of 3.0. Ezio Melotti <ezio.melotti@gmail.com> parents: 70304 diff changeset	16 converting your sources to Python 3.
47010 7e18d6593824 Added documentation stub for ConfigParser. Alexandre Vassalotti <alexandre@peadrop.com> parents: 47009 diff changeset	17
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 pair: .ini; file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 pair: configuration; file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 single: ini file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 single: Windows ini file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 This module defines the class :class:`ConfigParser`. The :class:`ConfigParser`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 class implements a basic configuration file parser language which provides a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 structure similar to what you would find on Microsoft Windows INI files. You
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 can use this to write Python programs which can be customized by end users
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 easily.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29
53573 503f0f41f35f Merged revisions 72007-72010,72036-72037 via svnmerge from Georg Brandl <georg@python.org> parents: 51929 diff changeset	30 .. note::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31
53573 503f0f41f35f Merged revisions 72007-72010,72036-72037 via svnmerge from Georg Brandl <georg@python.org> parents: 51929 diff changeset	32 This library does not interpret or write the value-type prefixes used in
503f0f41f35f Merged revisions 72007-72010,72036-72037 via svnmerge from Georg Brandl <georg@python.org> parents: 51929 diff changeset	33 the Windows Registry extended version of INI syntax.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
69341 5a09a335e8e7 #9101: backport json reference in configparser doc. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	35 .. seealso::
5a09a335e8e7 #9101: backport json reference in configparser doc. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	36
5a09a335e8e7 #9101: backport json reference in configparser doc. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	37 Module :mod:`shlex`
5a09a335e8e7 #9101: backport json reference in configparser doc. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	38 Support for a creating Unix shell-like mini-languages which can be used
5a09a335e8e7 #9101: backport json reference in configparser doc. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	39 as an alternate format for application configuration files.
5a09a335e8e7 #9101: backport json reference in configparser doc. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	40
5a09a335e8e7 #9101: backport json reference in configparser doc. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	41 Module :mod:`json`
5a09a335e8e7 #9101: backport json reference in configparser doc. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	42 The json module implements a subset of JavaScript syntax which can also
5a09a335e8e7 #9101: backport json reference in configparser doc. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	43 be used for this purpose.
5a09a335e8e7 #9101: backport json reference in configparser doc. Ezio Melotti <ezio.melotti@gmail.com> parents: 68256 diff changeset	44
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 The configuration file consists of sections, led by a ``[section]`` header and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 followed by ``name: value`` entries, with continuations in the style of
46104 1dd00016a69c Add an example for an RFC 822 continuation. Georg Brandl <georg@python.org> parents: 45445 diff changeset	47 :rfc:`822` (see section 3.1.1, "LONG HEADER FIELDS"); ``name=value`` is also
1dd00016a69c Add an example for an RFC 822 continuation. Georg Brandl <georg@python.org> parents: 45445 diff changeset	48 accepted. Note that leading whitespace is removed from values. The optional
1dd00016a69c Add an example for an RFC 822 continuation. Georg Brandl <georg@python.org> parents: 45445 diff changeset	49 values can contain format strings which refer to other values in the same
1dd00016a69c Add an example for an RFC 822 continuation. Georg Brandl <georg@python.org> parents: 45445 diff changeset	50 section, or values in a special ``DEFAULT`` section. Additional defaults can be
1dd00016a69c Add an example for an RFC 822 continuation. Georg Brandl <georg@python.org> parents: 45445 diff changeset	51 provided on initialization and retrieval. Lines beginning with ``'#'`` or
1dd00016a69c Add an example for an RFC 822 continuation. Georg Brandl <georg@python.org> parents: 45445 diff changeset	52 ``';'`` are ignored and may be used to provide comments.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
63503 e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	54 Configuration files may include comments, prefixed by specific characters (``#``
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	55 and ``;``). Comments may appear on their own in an otherwise empty line, or may
66110 40eb0c9a3f92 fix typo: spection -> section Fred Drake <fdrake@acm.org> parents: 63468 diff changeset	56 be entered in lines holding values or section names. In the latter case, they
63503 e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	57 need to be preceded by a whitespace character to be recognized as a comment.
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	58 (For backwards compatibility, only ``;`` starts an inline comment, while ``#``
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	59 does not.)
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	60
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	61 On top of the core functionality, :class:`SafeConfigParser` supports
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	62 interpolation. This means values can contain format strings which refer to
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	63 other values in the same section, or values in a special ``DEFAULT`` section.
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	64 Additional defaults can be provided on initialization.
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	65
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 [My Section]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 foodir: %(dir)s/whatever
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 dir=frob
46104 1dd00016a69c Add an example for an RFC 822 continuation. Georg Brandl <georg@python.org> parents: 45445 diff changeset	71 long: this value continues
1dd00016a69c Add an example for an RFC 822 continuation. Georg Brandl <georg@python.org> parents: 45445 diff changeset	72 in the next line
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 would resolve the ``%(dir)s`` to the value of ``dir`` (``frob`` in this case).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 All reference expansions are done on demand.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 Default values can be specified by passing them into the :class:`ConfigParser`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 constructor as a dictionary. Additional defaults may be passed into the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 :meth:`get` method which will override all others.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80
56818 3e15a07a32fa Merged revisions 74209 via svnmerge from Georg Brandl <georg@python.org> parents: 53573 diff changeset	81 Sections are normally stored in a built-in dictionary. An alternative dictionary
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 type can be passed to the :class:`ConfigParser` constructor. For example, if a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 dictionary type is passed that sorts its keys, the sections will be sorted on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 write-back, as will be the keys within each section.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86
58948 6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	87 .. class:: RawConfigParser([defaults[, dict_type[, allow_no_value]]])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 The basic configuration object. When defaults is given, it is initialized
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 into the dictionary of intrinsic defaults. When dict_type is given, it will
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 be used to create the dictionary objects for the list of sections, for the
58948 6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	92 options within a section, and for the default values. When allow_no_value
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	93 is true (default: ``False``), options without values are accepted; the value
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	94 presented for these is ``None``.
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	95
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	96 This class does not
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 support the magical interpolation behavior.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98
69670 c7ce67c9237a Closes #11786: ConfigParser.[Raw]ConfigParser optionxform(). Łukasz Langa <lukasz@langa.pl> parents: 63503 diff changeset	99 All option names are passed through the :meth:`optionxform` method. Its
c7ce67c9237a Closes #11786: ConfigParser.[Raw]ConfigParser optionxform(). Łukasz Langa <lukasz@langa.pl> parents: 63503 diff changeset	100 default implementation converts option names to lower case.
c7ce67c9237a Closes #11786: ConfigParser.[Raw]ConfigParser optionxform(). Łukasz Langa <lukasz@langa.pl> parents: 63503 diff changeset	101
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 .. versionchanged:: 2.6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 dict_type was added.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106
51964 6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	107 .. versionchanged:: 2.7
6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	108 The default dict_type is :class:`collections.OrderedDict`.
58948 6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	109 allow_no_value was added.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111
58948 6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	112 .. class:: ConfigParser([defaults[, dict_type[, allow_no_value]]])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 Derived class of :class:`RawConfigParser` that implements the magical
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 interpolation feature and adds optional arguments to the :meth:`get` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 :meth:`items` methods. The values in defaults must be appropriate for the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 ``%()s`` string interpolation. Note that __name__ is an intrinsic default;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 its value is the section name, and will override any value provided in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119 defaults.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 All option names used in interpolation will be passed through the
69670 c7ce67c9237a Closes #11786: ConfigParser.[Raw]ConfigParser optionxform(). Łukasz Langa <lukasz@langa.pl> parents: 63503 diff changeset	122 :meth:`optionxform` method just like any other option name reference. Using
c7ce67c9237a Closes #11786: ConfigParser.[Raw]ConfigParser optionxform(). Łukasz Langa <lukasz@langa.pl> parents: 63503 diff changeset	123 the default implementation of :meth:`optionxform`, the values ``foo %(bar)s``
c7ce67c9237a Closes #11786: ConfigParser.[Raw]ConfigParser optionxform(). Łukasz Langa <lukasz@langa.pl> parents: 63503 diff changeset	124 and ``foo %(BAR)s`` are equivalent.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
51964 6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	126 .. versionadded:: 2.3
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
51964 6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	128 .. versionchanged:: 2.6
6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	129 dict_type was added.
6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	130
6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	131 .. versionchanged:: 2.7
6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	132 The default dict_type is :class:`collections.OrderedDict`.
58948 6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	133 allow_no_value was added.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135
58948 6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	136 .. class:: SafeConfigParser([defaults[, dict_type[, allow_no_value]]])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 Derived class of :class:`ConfigParser` that implements a more-sane variant of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 the magical interpolation feature. This implementation is more predictable as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 well. New applications should prefer this version if they don't need to be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 compatible with older versions of Python.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44051 diff changeset	143 .. XXX Need to explain what's safer/more predictable about it.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146
51964 6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	147 .. versionchanged:: 2.6
6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	148 dict_type was added.
6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	149
6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	150 .. versionchanged:: 2.7
6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	151 The default dict_type is :class:`collections.OrderedDict`.
58948 6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	152 allow_no_value was added.
51964 6b1b2e7a06e9 Backport 70111: Let configparser use ordered dicts by default. Raymond Hettinger <python@rcn.com> parents: 51928 diff changeset	153
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154
63503 e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	155 .. exception:: Error
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	156
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	157 Base class for all other configparser exceptions.
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	158
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	159
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 .. exception:: NoSectionError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 Exception raised when a specified section is not found.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 .. exception:: DuplicateSectionError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 Exception raised if :meth:`add_section` is called with the name of a section
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 that is already present.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 .. exception:: NoOptionError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 Exception raised when a specified option is not found in the specified section.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 .. exception:: InterpolationError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 Base class for exceptions raised when problems occur performing string
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 interpolation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 .. exception:: InterpolationDepthError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 Exception raised when string interpolation cannot be completed because the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 number of iterations exceeds :const:`MAX_INTERPOLATION_DEPTH`. Subclass of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 :exc:`InterpolationError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 .. exception:: InterpolationMissingOptionError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 Exception raised when an option referenced from a value does not exist. Subclass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 of :exc:`InterpolationError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 .. exception:: InterpolationSyntaxError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 Exception raised when the source text into which substitutions are made does not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 conform to the required syntax. Subclass of :exc:`InterpolationError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 .. exception:: MissingSectionHeaderError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 Exception raised when attempting to parse a file which has no section headers.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 .. exception:: ParsingError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 Exception raised when errors occur attempting to parse a file.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 .. data:: MAX_INTERPOLATION_DEPTH
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 The maximum depth for recursive interpolation for :meth:`get` when the raw
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 parameter is false. This is relevant only for the :class:`ConfigParser` class.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 Module :mod:`shlex`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 Support for a creating Unix shell-like mini-languages which can be used as an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 alternate format for application configuration files.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 .. _rawconfigparser-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 RawConfigParser Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 :class:`RawConfigParser` instances have the following methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 .. method:: RawConfigParser.defaults()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 Return a dictionary containing the instance-wide defaults.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 .. method:: RawConfigParser.sections()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 Return a list of the sections available; ``DEFAULT`` is not included in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 list.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 .. method:: RawConfigParser.add_section(section)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 Add a section named section to the instance. If a section by the given name
45445 dda92a097e8c Issue 1781. Now ConfigParser.add_section does not let you add a Facundo Batista <facundobatista@gmail.com> parents: 44838 diff changeset	250 already exists, :exc:`DuplicateSectionError` is raised. If the name
dda92a097e8c Issue 1781. Now ConfigParser.add_section does not let you add a Facundo Batista <facundobatista@gmail.com> parents: 44838 diff changeset	251 ``DEFAULT`` (or any of it's case-insensitive variants) is passed,
dda92a097e8c Issue 1781. Now ConfigParser.add_section does not let you add a Facundo Batista <facundobatista@gmail.com> parents: 44838 diff changeset	252 :exc:`ValueError` is raised.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 .. method:: RawConfigParser.has_section(section)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 Indicates whether the named section is present in the configuration. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 ``DEFAULT`` section is not acknowledged.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 .. method:: RawConfigParser.options(section)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 Returns a list of options available in the specified section.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 .. method:: RawConfigParser.has_option(section, option)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 If the given section exists, and contains the given option, return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 :const:`True`; otherwise return :const:`False`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 .. versionadded:: 1.6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 .. method:: RawConfigParser.read(filenames)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275 Attempt to read and parse a list of filenames, returning a list of filenames
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 which were successfully parsed. If filenames is a string or Unicode string,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 it is treated as a single filename. If a file named in filenames cannot be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 opened, that file will be ignored. This is designed so that you can specify a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 list of potential configuration file locations (for example, the current
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 directory, the user's home directory, and some system-wide directory), and all
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 existing configuration files in the list will be read. If none of the named
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 files exist, the :class:`ConfigParser` instance will contain an empty dataset.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 An application which requires initial values to be loaded from a file should
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 load the required file or files using :meth:`readfp` before calling :meth:`read`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 for any optional files::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	287 import ConfigParser, os
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	289 config = ConfigParser.ConfigParser()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 config.readfp(open('defaults.cfg'))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 .. versionchanged:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 Returns list of successfully parsed filenames.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 .. method:: RawConfigParser.readfp(fp[, filename])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 Read and parse configuration data from the file or file-like object in fp
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 (only the :meth:`readline` method is used). If filename is omitted and fp
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301 has a :attr:`name` attribute, that is used for filename; the default is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 ``<???>``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 .. method:: RawConfigParser.get(section, option)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 Get an option value for the named section.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 .. method:: RawConfigParser.getint(section, option)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 A convenience method which coerces the option in the specified section to an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 integer.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 .. method:: RawConfigParser.getfloat(section, option)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 A convenience method which coerces the option in the specified section to a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 floating point number.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 .. method:: RawConfigParser.getboolean(section, option)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 A convenience method which coerces the option in the specified section to a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 Boolean value. Note that the accepted values for the option are ``"1"``,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 ``"yes"``, ``"true"``, and ``"on"``, which cause this method to return ``True``,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 and ``"0"``, ``"no"``, ``"false"``, and ``"off"``, which cause it to return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 ``False``. These string values are checked in a case-insensitive manner. Any
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 other value will cause it to raise :exc:`ValueError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 .. method:: RawConfigParser.items(section)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 Return a list of ``(name, value)`` pairs for each option in the given section.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 .. method:: RawConfigParser.set(section, option, value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 If the given section exists, set the given option to the specified value;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 otherwise raise :exc:`NoSectionError`. While it is possible to use
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 :class:`RawConfigParser` (or :class:`ConfigParser` with raw parameters set to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 true) for internal storage of non-string values, full functionality (including
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 interpolation and output to files) can only be achieved using string values.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 .. versionadded:: 1.6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 .. method:: RawConfigParser.write(fileobject)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 Write a representation of the configuration to the specified file object. This
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 representation can be parsed by a future :meth:`read` call.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 .. versionadded:: 1.6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 .. method:: RawConfigParser.remove_option(section, option)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 Remove the specified option from the specified section. If the section does
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 not exist, raise :exc:`NoSectionError`. If the option existed to be removed,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 return :const:`True`; otherwise return :const:`False`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 .. versionadded:: 1.6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 .. method:: RawConfigParser.remove_section(section)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 Remove the specified section from the configuration. If the section in fact
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 existed, return ``True``. Otherwise return ``False``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 .. method:: RawConfigParser.optionxform(option)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372
56824 b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	373 Transforms the option name option as found in an input file or as passed in
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	374 by client code to the form that should be used in the internal structures.
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	375 The default implementation returns a lower-case version of option;
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	376 subclasses may override this or client code can set an attribute of this name
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	377 on instances to affect this behavior.
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	378
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	379 You don't necessarily need to subclass a ConfigParser to use this method, you
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	380 can also re-set it on an instance, to a function that takes a string
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	381 argument. Setting it to ``str``, for example, would make option names case
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	382 sensitive::
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	383
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	384 cfgparser = ConfigParser()
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	385 ...
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	386 cfgparser.optionxform = str
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	387
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	388 Note that when reading configuration files, whitespace around the
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	389 option names are stripped before :meth:`optionxform` is called.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 .. _configparser-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 ConfigParser Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 --------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 The :class:`ConfigParser` class extends some methods of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 :class:`RawConfigParser` interface, adding some optional arguments.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 .. method:: ConfigParser.get(section, option[, raw[, vars]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402
63503 e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	403 Get an option value for the named section. If vars is provided, it
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	404 must be a dictionary. The option is looked up in vars (if provided),
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	405 section, and in defaults in that order.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406
63503 e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	407 All the ``'%'`` interpolations are expanded in the return values, unless the
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	408 raw argument is true. Values for interpolation keys are looked up in the
e8fc9a9e1991 Merged revisions 83452,83457,83466,83471,83475,83480,83486 via svnmerge from Georg Brandl <georg@python.org> parents: 56824 diff changeset	409 same manner as the option.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 .. method:: ConfigParser.items(section[, raw[, vars]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 Return a list of ``(name, value)`` pairs for each option in the given section.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 Optional arguments have the same meaning as for the :meth:`get` method.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 .. _safeconfigparser-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 SafeConfigParser Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424 The :class:`SafeConfigParser` class implements the same extended interface as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 :class:`ConfigParser`, with the following addition:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 .. method:: SafeConfigParser.set(section, option, value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 If the given section exists, set the given option to the specified value;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 otherwise raise :exc:`NoSectionError`. value must be a string (:class:`str`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 or :class:`unicode`); if not, :exc:`TypeError` is raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 .. versionadded:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	436
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	437 Examples
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	438 --------
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	439
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	440 An example of writing to a configuration file::
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	441
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	442 import ConfigParser
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	443
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	444 config = ConfigParser.RawConfigParser()
e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	445
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	446 # When adding sections or items, add them in the reverse order of
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	447 # how you want them to be displayed in the actual file.
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	448 # In addition, please note that using RawConfigParser's and the raw
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	449 # mode of ConfigParser's respective set functions, you can assign
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	450 # non-string values to keys internally, but will receive an error
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	451 # when attempting to write to a file or when you get it in non-raw
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	452 # mode. SafeConfigParser does not allow such assignments to take place.
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	453 config.add_section('Section1')
79264 1ee270d522f3 #16085: Don't promote shadowing builtins in the configparser example. R David Murray <rdmurray@bitdance.com> parents: 76732 diff changeset	454 config.set('Section1', 'an_int', '15')
1ee270d522f3 #16085: Don't promote shadowing builtins in the configparser example. R David Murray <rdmurray@bitdance.com> parents: 76732 diff changeset	455 config.set('Section1', 'a_bool', 'true')
1ee270d522f3 #16085: Don't promote shadowing builtins in the configparser example. R David Murray <rdmurray@bitdance.com> parents: 76732 diff changeset	456 config.set('Section1', 'a_float', '3.1415')
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	457 config.set('Section1', 'baz', 'fun')
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	458 config.set('Section1', 'bar', 'Python')
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	459 config.set('Section1', 'foo', '%(bar)s is %(baz)s!')
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	460
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	461 # Writing our configuration file to 'example.cfg'
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	462 with open('example.cfg', 'wb') as configfile:
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	463 config.write(configfile)
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	464
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	465 An example of reading the configuration file again::
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	466
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	467 import ConfigParser
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	468
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	469 config = ConfigParser.RawConfigParser()
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	470 config.read('example.cfg')
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	471
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	472 # getfloat() raises an exception if the value is not a float
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	473 # getint() and getboolean() also do this for their respective types
79264 1ee270d522f3 #16085: Don't promote shadowing builtins in the configparser example. R David Murray <rdmurray@bitdance.com> parents: 76732 diff changeset	474 a_float = config.getfloat('Section1', 'a_float')
1ee270d522f3 #16085: Don't promote shadowing builtins in the configparser example. R David Murray <rdmurray@bitdance.com> parents: 76732 diff changeset	475 an_int = config.getint('Section1', 'an_int')
1ee270d522f3 #16085: Don't promote shadowing builtins in the configparser example. R David Murray <rdmurray@bitdance.com> parents: 76732 diff changeset	476 print a_float + an_int
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	477
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	478 # Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	479 # This is because we are using a RawConfigParser().
79264 1ee270d522f3 #16085: Don't promote shadowing builtins in the configparser example. R David Murray <rdmurray@bitdance.com> parents: 76732 diff changeset	480 if config.getboolean('Section1', 'a_bool'):
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	481 print config.get('Section1', 'foo')
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	482
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	483 To get interpolation, you will need to use a :class:`ConfigParser` or
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	484 :class:`SafeConfigParser`::
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	485
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	486 import ConfigParser
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	487
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	488 config = ConfigParser.ConfigParser()
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	489 config.read('example.cfg')
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	490
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	491 # Set the third, optional argument of get to 1 if you wish to use raw mode.
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	492 print config.get('Section1', 'foo', 0) # -> "Python is fun!"
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	493 print config.get('Section1', 'foo', 1) # -> "%(bar)s is %(baz)s!"
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	494
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	495 # The optional fourth argument is a dict with members that will take
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	496 # precedence in interpolation.
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	497 print config.get('Section1', 'foo', 0, {'bar': 'Documentation',
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	498 'baz': 'evil'})
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	499
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	500 Defaults are available in all three types of ConfigParsers. They are used in
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	501 interpolation if an option used is not defined elsewhere. ::
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	502
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	503 import ConfigParser
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	504
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	505 # New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	506 config = ConfigParser.SafeConfigParser({'bar': 'Life', 'baz': 'hard'})
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	507 config.read('example.cfg')
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	508
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	509 print config.get('Section1', 'foo') # -> "Python is fun!"
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	510 config.remove_option('Section1', 'bar')
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	511 config.remove_option('Section1', 'baz')
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	512 print config.get('Section1', 'foo') # -> "Life is hard!"
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	513
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	514 The function ``opt_move`` below can be used to move options between sections::
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	515
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	516 def opt_move(config, section1, section2, option):
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	517 try:
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	518 config.set(section2, option, config.get(section1, option, 1))
47252 e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports. Georg Brandl <georg@python.org> parents: 47010 diff changeset	519 except ConfigParser.NoSectionError:
44051 c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	520 # Create non-existent section
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	521 config.add_section(section2)
c024b894d929 Add examples to the ConfigParser documentation. Georg Brandl <georg@python.org> parents: 42604 diff changeset	522 opt_move(config, section1, section2, option)
44838 f6d4a2c49531 Fix example. Georg Brandl <georg@python.org> parents: 44383 diff changeset	523 else:
f6d4a2c49531 Fix example. Georg Brandl <georg@python.org> parents: 44383 diff changeset	524 config.remove_option(section1, option)
58948 6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	525
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	526 Some configuration files are known to include settings without values, but which
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	527 otherwise conform to the syntax supported by :mod:`ConfigParser`. The
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	528 allow_no_value parameter to the constructor can be used to indicate that such
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	529 values should be accepted:
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	530
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	531 .. doctest::
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	532
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	533 >>> import ConfigParser
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	534 >>> import io
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	535
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	536 >>> sample_config = """
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	537 ... [mysqld]
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	538 ... user = mysql
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	539 ... pid-file = /var/run/mysqld/mysqld.pid
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	540 ... skip-external-locking
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	541 ... old_passwords = 1
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	542 ... skip-bdb
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	543 ... skip-innodb
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	544 ... """
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	545 >>> config = ConfigParser.RawConfigParser(allow_no_value=True)
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	546 >>> config.readfp(io.BytesIO(sample_config))
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	547
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	548 >>> # Settings with values are treated as before:
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	549 >>> config.get("mysqld", "user")
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	550 'mysql'
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	551
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	552 >>> # Settings without values provide None:
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	553 >>> config.get("mysqld", "skip-bdb")
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	554
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	555 >>> # Settings which aren't specified still raise an error:
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	556 >>> config.get("mysqld", "does-not-exist")
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	557 Traceback (most recent call last):
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	558 ...
6e74d3e51d33 - apply patch from issue 7005 Fred Drake <fdrake@acm.org> parents: 56696 diff changeset	559 ConfigParser.NoOptionError: No option 'does-not-exist' in section: 'mysqld'

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/configparser.rst @ 79675:c0a2294de787 2.7