cpython/Doc/library/configparser.rst

501 lines
17 KiB
ReStructuredText
Raw Normal View History

:mod:`configparser` --- Configuration file parser
2007-08-15 11:28:22 -03:00
=================================================
.. module:: configparser
2007-08-15 11:28:22 -03:00
:synopsis: Configuration file parser.
2007-08-15 11:28:22 -03:00
.. moduleauthor:: Ken Manheimer <klm@zope.com>
.. moduleauthor:: Barry Warsaw <bwarsaw@python.org>
.. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
.. sectionauthor:: Christopher G. Petrilli <petrilli@amber.org>
.. index::
pair: .ini; file
pair: configuration; file
single: ini file
single: Windows ini file
This module defines the class :class:`ConfigParser`. The :class:`ConfigParser`
class implements a basic configuration file parser language which provides a
structure similar to what you would find on Microsoft Windows INI files. You
can use this to write Python programs which can be customized by end users
easily.
.. note::
2007-08-15 11:28:22 -03:00
This library does *not* interpret or write the value-type prefixes used in
the Windows Registry extended version of INI syntax.
2007-08-15 11:28:22 -03:00
The configuration file consists of sections, led by a ``[section]`` header and
followed by ``name: value`` entries, with continuations in the style of
Merged revisions 61913,61915-61916,61918-61919,61922-61926,61928-61929,61931,61935,61938,61943 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r61913 | benjamin.peterson | 2008-03-25 22:14:42 +0100 (Tue, 25 Mar 2008) | 2 lines Merged the ACKS from py3k ........ r61915 | thomas.heller | 2008-03-25 22:18:39 +0100 (Tue, 25 Mar 2008) | 1 line Make _ctypes.c PY_SSIZE_T_CLEAN. ........ r61916 | benjamin.peterson | 2008-03-25 22:55:50 +0100 (Tue, 25 Mar 2008) | 3 lines Opps! I merged the revisions, but forgot to add the header to ACKS ........ r61918 | andrew.kuchling | 2008-03-26 01:16:50 +0100 (Wed, 26 Mar 2008) | 1 line Minor docstring typos ........ r61919 | andrew.kuchling | 2008-03-26 01:30:02 +0100 (Wed, 26 Mar 2008) | 1 line Add various items ........ r61922 | neal.norwitz | 2008-03-26 05:55:51 +0100 (Wed, 26 Mar 2008) | 6 lines Try to get this test to be less flaky. It was failing sometimes because the connect would succeed before the timeout occurred. Try using an address and port that hopefully doesn't exist to ensure we get no response. If this doesn't work, we can use a public address close to python.org and hopefully that address never gets taken. ........ r61923 | jerry.seutter | 2008-03-26 06:03:03 +0100 (Wed, 26 Mar 2008) | 1 line Changed test so it no longer runs as a side effect of importing. ........ r61924 | neal.norwitz | 2008-03-26 06:19:41 +0100 (Wed, 26 Mar 2008) | 5 lines Ensure that the mailbox is closed to prevent problems on Windows with removing an open file. This doesn't seem to be a problem in 2.6, but that appears to be somewhat accidental (specific to reference counting). When this gets merged to 3.0, it will make the 3.0 code simpler. ........ r61925 | jerry.seutter | 2008-03-26 06:32:51 +0100 (Wed, 26 Mar 2008) | 1 line Changed test so it no longer runs as a side effect of importing. ........ r61926 | jerry.seutter | 2008-03-26 06:58:14 +0100 (Wed, 26 Mar 2008) | 1 line Changed test so it no longer runs as a side effect of importing. ........ r61928 | georg.brandl | 2008-03-26 10:04:36 +0100 (Wed, 26 Mar 2008) | 2 lines Add Josiah. ........ r61929 | georg.brandl | 2008-03-26 10:32:46 +0100 (Wed, 26 Mar 2008) | 2 lines Add an example for an RFC 822 continuation. ........ r61931 | benjamin.peterson | 2008-03-26 12:57:47 +0100 (Wed, 26 Mar 2008) | 2 lines Added help options to PDB ........ r61935 | christian.heimes | 2008-03-26 13:32:49 +0100 (Wed, 26 Mar 2008) | 1 line Prepare integration of bytearray backport branch ........ r61938 | christian.heimes | 2008-03-26 13:50:43 +0100 (Wed, 26 Mar 2008) | 3 lines Removed merge tracking for "svnmerge" for svn+ssh://pythondev@svn.python.org/python/branches/trunk-bytearray ........ r61943 | georg.brandl | 2008-03-26 13:57:47 +0100 (Wed, 26 Mar 2008) | 2 lines Fix and simplify error handling, silencing a compiler warning. ........
2008-03-26 10:45:42 -03:00
:rfc:`822` (see section 3.1.1, "LONG HEADER FIELDS"); ``name=value`` is also
accepted. Note that leading whitespace is removed from values. The optional
values can contain format strings which refer to other values in the same
section, or values in a special ``DEFAULT`` section. Additional defaults can be
provided on initialization and retrieval. Lines beginning with ``'#'`` or
``';'`` are ignored and may be used to provide comments.
2007-08-15 11:28:22 -03:00
For example::
[My Section]
foodir: %(dir)s/whatever
dir=frob
Merged revisions 61913,61915-61916,61918-61919,61922-61926,61928-61929,61931,61935,61938,61943 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r61913 | benjamin.peterson | 2008-03-25 22:14:42 +0100 (Tue, 25 Mar 2008) | 2 lines Merged the ACKS from py3k ........ r61915 | thomas.heller | 2008-03-25 22:18:39 +0100 (Tue, 25 Mar 2008) | 1 line Make _ctypes.c PY_SSIZE_T_CLEAN. ........ r61916 | benjamin.peterson | 2008-03-25 22:55:50 +0100 (Tue, 25 Mar 2008) | 3 lines Opps! I merged the revisions, but forgot to add the header to ACKS ........ r61918 | andrew.kuchling | 2008-03-26 01:16:50 +0100 (Wed, 26 Mar 2008) | 1 line Minor docstring typos ........ r61919 | andrew.kuchling | 2008-03-26 01:30:02 +0100 (Wed, 26 Mar 2008) | 1 line Add various items ........ r61922 | neal.norwitz | 2008-03-26 05:55:51 +0100 (Wed, 26 Mar 2008) | 6 lines Try to get this test to be less flaky. It was failing sometimes because the connect would succeed before the timeout occurred. Try using an address and port that hopefully doesn't exist to ensure we get no response. If this doesn't work, we can use a public address close to python.org and hopefully that address never gets taken. ........ r61923 | jerry.seutter | 2008-03-26 06:03:03 +0100 (Wed, 26 Mar 2008) | 1 line Changed test so it no longer runs as a side effect of importing. ........ r61924 | neal.norwitz | 2008-03-26 06:19:41 +0100 (Wed, 26 Mar 2008) | 5 lines Ensure that the mailbox is closed to prevent problems on Windows with removing an open file. This doesn't seem to be a problem in 2.6, but that appears to be somewhat accidental (specific to reference counting). When this gets merged to 3.0, it will make the 3.0 code simpler. ........ r61925 | jerry.seutter | 2008-03-26 06:32:51 +0100 (Wed, 26 Mar 2008) | 1 line Changed test so it no longer runs as a side effect of importing. ........ r61926 | jerry.seutter | 2008-03-26 06:58:14 +0100 (Wed, 26 Mar 2008) | 1 line Changed test so it no longer runs as a side effect of importing. ........ r61928 | georg.brandl | 2008-03-26 10:04:36 +0100 (Wed, 26 Mar 2008) | 2 lines Add Josiah. ........ r61929 | georg.brandl | 2008-03-26 10:32:46 +0100 (Wed, 26 Mar 2008) | 2 lines Add an example for an RFC 822 continuation. ........ r61931 | benjamin.peterson | 2008-03-26 12:57:47 +0100 (Wed, 26 Mar 2008) | 2 lines Added help options to PDB ........ r61935 | christian.heimes | 2008-03-26 13:32:49 +0100 (Wed, 26 Mar 2008) | 1 line Prepare integration of bytearray backport branch ........ r61938 | christian.heimes | 2008-03-26 13:50:43 +0100 (Wed, 26 Mar 2008) | 3 lines Removed merge tracking for "svnmerge" for svn+ssh://pythondev@svn.python.org/python/branches/trunk-bytearray ........ r61943 | georg.brandl | 2008-03-26 13:57:47 +0100 (Wed, 26 Mar 2008) | 2 lines Fix and simplify error handling, silencing a compiler warning. ........
2008-03-26 10:45:42 -03:00
long: this value continues
in the next line
2007-08-15 11:28:22 -03:00
would resolve the ``%(dir)s`` to the value of ``dir`` (``frob`` in this case).
All reference expansions are done on demand.
Default values can be specified by passing them into the :class:`ConfigParser`
constructor as a dictionary. Additional defaults may be passed into the
:meth:`get` method which will override all others.
Sections are normally stored in a built-in dictionary. An alternative dictionary
2007-08-15 11:28:22 -03:00
type can be passed to the :class:`ConfigParser` constructor. For example, if a
dictionary type is passed that sorts its keys, the sections will be sorted on
write-back, as will be the keys within each section.
.. class:: RawConfigParser(defaults=None, dict_type=collections.OrderedDict,
allow_no_value=False)
2007-08-15 11:28:22 -03:00
The basic configuration object. When *defaults* is given, it is initialized
into the dictionary of intrinsic defaults. When *dict_type* is given, it will
be used to create the dictionary objects for the list of sections, for the
options within a section, and for the default values. When *allow_no_value*
is true (default: ``False``), options without values are accepted; the value
presented for these is ``None``.
This class does not
2007-08-15 11:28:22 -03:00
support the magical interpolation behavior.
2009-03-02 20:23:19 -04:00
.. versionchanged:: 3.1
The default *dict_type* is :class:`collections.OrderedDict`.
.. versionchanged:: 3.2
*allow_no_value* was added.
2007-08-15 11:28:22 -03:00
.. class:: ConfigParser(defaults=None, dict_type=collections.OrderedDict,
allow_no_value=False)
2007-08-15 11:28:22 -03:00
Derived class of :class:`RawConfigParser` that implements the magical
interpolation feature and adds optional arguments to the :meth:`get` and
:meth:`items` methods. The values in *defaults* must be appropriate for the
``%()s`` string interpolation. Note that *__name__* is an intrinsic default;
its value is the section name, and will override any value provided in
*defaults*.
All option names used in interpolation will be passed through the
:meth:`optionxform` method just like any other option name reference. For
example, using the default implementation of :meth:`optionxform` (which converts
option names to lower case), the values ``foo %(bar)s`` and ``foo %(BAR)s`` are
equivalent.
2009-03-02 20:23:19 -04:00
.. versionchanged:: 3.1
The default *dict_type* is :class:`collections.OrderedDict`.
.. versionchanged:: 3.2
*allow_no_value* was added.
2007-08-15 11:28:22 -03:00
.. class:: SafeConfigParser(defaults=None, dict_type=collections.OrderedDict,
allow_no_value=False)
2007-08-15 11:28:22 -03:00
Derived class of :class:`ConfigParser` that implements a more-sane variant of
the magical interpolation feature. This implementation is more predictable as
well. New applications should prefer this version if they don't need to be
compatible with older versions of Python.
.. XXX Need to explain what's safer/more predictable about it.
2007-08-15 11:28:22 -03:00
2009-03-02 20:23:19 -04:00
.. versionchanged:: 3.1
The default *dict_type* is :class:`collections.OrderedDict`.
.. versionchanged:: 3.2
*allow_no_value* was added.
2007-08-15 11:28:22 -03:00
.. exception:: NoSectionError
Exception raised when a specified section is not found.
.. exception:: DuplicateSectionError
Exception raised if :meth:`add_section` is called with the name of a section
that is already present.
.. exception:: NoOptionError
Exception raised when a specified option is not found in the specified section.
.. exception:: InterpolationError
Base class for exceptions raised when problems occur performing string
interpolation.
.. exception:: InterpolationDepthError
Exception raised when string interpolation cannot be completed because the
number of iterations exceeds :const:`MAX_INTERPOLATION_DEPTH`. Subclass of
:exc:`InterpolationError`.
.. exception:: InterpolationMissingOptionError
Exception raised when an option referenced from a value does not exist. Subclass
of :exc:`InterpolationError`.
.. exception:: InterpolationSyntaxError
Exception raised when the source text into which substitutions are made does not
conform to the required syntax. Subclass of :exc:`InterpolationError`.
.. exception:: MissingSectionHeaderError
Exception raised when attempting to parse a file which has no section headers.
.. exception:: ParsingError
Exception raised when errors occur attempting to parse a file.
.. data:: MAX_INTERPOLATION_DEPTH
The maximum depth for recursive interpolation for :meth:`get` when the *raw*
parameter is false. This is relevant only for the :class:`ConfigParser` class.
.. seealso::
Module :mod:`shlex`
Support for a creating Unix shell-like mini-languages which can be used as an
alternate format for application configuration files.
.. _rawconfigparser-objects:
RawConfigParser Objects
-----------------------
:class:`RawConfigParser` instances have the following methods:
.. method:: RawConfigParser.defaults()
Return a dictionary containing the instance-wide defaults.
.. method:: RawConfigParser.sections()
Return a list of the sections available; ``DEFAULT`` is not included in the
list.
.. method:: RawConfigParser.add_section(section)
Add a section named *section* to the instance. If a section by the given name
Merged revisions 60481,60485,60489-60492,60494-60496,60498-60499,60501-60503,60505-60506,60508-60509,60523-60524,60532,60543,60545,60547-60548,60552,60554,60556-60559,60561-60562,60569,60571-60572,60574,60576-60583,60585-60586,60589,60591,60594-60595,60597-60598,60600-60601,60606-60612,60615,60617,60619-60621,60623-60625,60627-60629,60631,60633,60635,60647,60650,60652,60654,60656,60658-60659,60664-60666,60668-60670,60672,60676,60678,60680-60683,60685-60686,60688,60690,60692-60694,60697-60700,60705-60706,60708,60711,60714,60720,60724-60730,60732,60736,60742,60744,60746,60748,60750-60751,60753,60756-60757,60759-60761,60763-60764,60766,60769-60770,60774-60784,60787-60789,60793,60796,60799-60809,60812-60813,60815-60821,60823-60826,60828-60829,60831-60834,60836,60838-60839,60846-60849,60852-60854,60856-60859,60861-60870,60874-60875,60880-60881,60886,60888-60890,60892,60894-60898,60900,60902-60906,60908,60911-60917,60919-60920,60922,60926,60929-60931,60933-60935,60937,60939-60941,60943-60954,60959-60961,60963-60969,60971-60976 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60965 | eric.smith | 2008-02-22 18:43:17 +0100 (Fri, 22 Feb 2008) | 1 line Tests for bin() builtin. These need to get merged into py3k, which has no tests for bin. ........ r60968 | raymond.hettinger | 2008-02-22 20:50:06 +0100 (Fri, 22 Feb 2008) | 1 line Document itertools.product(). ........ r60969 | raymond.hettinger | 2008-02-23 03:20:41 +0100 (Sat, 23 Feb 2008) | 9 lines Improve the implementation of itertools.product() * Fix-up issues pointed-out by Neal Norwitz. * Add extensive comments. * The lz->result variable is now a tuple instead of a list. * Use fast macro getitem/setitem calls so most code is in-line. * Re-use the result tuple if available (modify in-place instead of copy). ........ r60972 | raymond.hettinger | 2008-02-23 05:03:50 +0100 (Sat, 23 Feb 2008) | 1 line Add more comments ........ r60973 | raymond.hettinger | 2008-02-23 11:04:15 +0100 (Sat, 23 Feb 2008) | 1 line Add recipe using itertools.product(). ........ r60974 | facundo.batista | 2008-02-23 13:01:13 +0100 (Sat, 23 Feb 2008) | 6 lines Issue 1881. Increased the stack limit from 500 to 1500. Also added a test for this (and because of this test you'll see in stderr a message that parser.c sends before raising MemoryError). Thanks Ralf Schmitt. ........ r60975 | facundo.batista | 2008-02-23 13:27:17 +0100 (Sat, 23 Feb 2008) | 4 lines Issue 1776581. Minor corrections to smtplib, and two small tests. Thanks Alan McIntyre. ........ r60976 | facundo.batista | 2008-02-23 13:46:10 +0100 (Sat, 23 Feb 2008) | 5 lines Issue 1781. Now ConfigParser.add_section does not let you add a DEFAULT section any more, because it duplicated sections with the rest of the machinery. Thanks Tim Lesher and Manuel Kaufmann. ........
2008-02-23 09:18:03 -04:00
already exists, :exc:`DuplicateSectionError` is raised. If the name
``DEFAULT`` (or any of it's case-insensitive variants) is passed,
:exc:`ValueError` is raised.
2007-08-15 11:28:22 -03:00
.. method:: RawConfigParser.has_section(section)
Indicates whether the named section is present in the configuration. The
``DEFAULT`` section is not acknowledged.
.. method:: RawConfigParser.options(section)
Returns a list of options available in the specified *section*.
.. method:: RawConfigParser.has_option(section, option)
If the given section exists, and contains the given option, return
:const:`True`; otherwise return :const:`False`.
.. method:: RawConfigParser.read(filenames)
Attempt to read and parse a list of filenames, returning a list of filenames
which were successfully parsed. If *filenames* is a string,
2007-08-15 11:28:22 -03:00
it is treated as a single filename. If a file named in *filenames* cannot be
opened, that file will be ignored. This is designed so that you can specify a
list of potential configuration file locations (for example, the current
directory, the user's home directory, and some system-wide directory), and all
existing configuration files in the list will be read. If none of the named
files exist, the :class:`ConfigParser` instance will contain an empty dataset.
An application which requires initial values to be loaded from a file should
load the required file or files using :meth:`readfp` before calling :meth:`read`
for any optional files::
import configparser, os
2007-08-15 11:28:22 -03:00
config = configparser.ConfigParser()
2007-08-15 11:28:22 -03:00
config.readfp(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
.. method:: RawConfigParser.readfp(fp, filename=None)
2007-08-15 11:28:22 -03:00
Read and parse configuration data from the file or file-like object in *fp*
(only the :meth:`readline` method is used). The file-like object must
operate in text mode, i.e. return strings from :meth:`readline`.
If *filename* is omitted and *fp* has a :attr:`name` attribute, that is used
for *filename*; the default is ``<???>``.
2007-08-15 11:28:22 -03:00
.. method:: RawConfigParser.get(section, option)
Get an *option* value for the named *section*.
.. method:: RawConfigParser.getint(section, option)
A convenience method which coerces the *option* in the specified *section* to an
integer.
.. method:: RawConfigParser.getfloat(section, option)
A convenience method which coerces the *option* in the specified *section* to a
floating point number.
.. method:: RawConfigParser.getboolean(section, option)
A convenience method which coerces the *option* in the specified *section* to a
Boolean value. Note that the accepted values for the option are ``"1"``,
``"yes"``, ``"true"``, and ``"on"``, which cause this method to return ``True``,
and ``"0"``, ``"no"``, ``"false"``, and ``"off"``, which cause it to return
``False``. These string values are checked in a case-insensitive manner. Any
other value will cause it to raise :exc:`ValueError`.
.. method:: RawConfigParser.items(section)
Return a list of ``(name, value)`` pairs for each option in the given *section*.
.. method:: RawConfigParser.set(section, option, value)
If the given section exists, set the given option to the specified value;
otherwise raise :exc:`NoSectionError`. While it is possible to use
:class:`RawConfigParser` (or :class:`ConfigParser` with *raw* parameters set to
true) for *internal* storage of non-string values, full functionality (including
interpolation and output to files) can only be achieved using string values.
.. method:: RawConfigParser.write(fileobject)
Write a representation of the configuration to the specified file object,
which must be opened in text mode (accepting strings). This representation
can be parsed by a future :meth:`read` call.
2007-08-15 11:28:22 -03:00
.. method:: RawConfigParser.remove_option(section, option)
Remove the specified *option* from the specified *section*. If the section does
not exist, raise :exc:`NoSectionError`. If the option existed to be removed,
return :const:`True`; otherwise return :const:`False`.
.. method:: RawConfigParser.remove_section(section)
Remove the specified *section* from the configuration. If the section in fact
existed, return ``True``. Otherwise return ``False``.
.. method:: RawConfigParser.optionxform(option)
Merged revisions 75365,75394,75402-75403,75418,75459,75484,75592-75596,75600,75602-75607,75610-75613,75616-75617,75623,75627,75640,75647,75696,75795 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r75365 | georg.brandl | 2009-10-11 22:16:16 +0200 (So, 11 Okt 2009) | 1 line Fix broken links found by "make linkcheck". scipy.org seems to be done right now, so I could not verify links going there. ........ r75394 | georg.brandl | 2009-10-13 20:10:59 +0200 (Di, 13 Okt 2009) | 1 line Fix markup. ........ r75402 | georg.brandl | 2009-10-14 17:51:48 +0200 (Mi, 14 Okt 2009) | 1 line #7125: fix typo. ........ r75403 | georg.brandl | 2009-10-14 17:57:46 +0200 (Mi, 14 Okt 2009) | 1 line #7126: os.environ changes *do* take effect in subprocesses started with os.system(). ........ r75418 | georg.brandl | 2009-10-14 20:48:32 +0200 (Mi, 14 Okt 2009) | 1 line #7116: str.join() takes an iterable. ........ r75459 | georg.brandl | 2009-10-17 10:57:43 +0200 (Sa, 17 Okt 2009) | 1 line Fix refleaks in _ctypes PyCSimpleType_New, which fixes the refleak seen in test___all__. ........ r75484 | georg.brandl | 2009-10-18 09:58:12 +0200 (So, 18 Okt 2009) | 1 line Fix missing word. ........ r75592 | georg.brandl | 2009-10-22 09:05:48 +0200 (Do, 22 Okt 2009) | 1 line Fix punctuation. ........ r75593 | georg.brandl | 2009-10-22 09:06:49 +0200 (Do, 22 Okt 2009) | 1 line Revert unintended change. ........ r75594 | georg.brandl | 2009-10-22 09:56:02 +0200 (Do, 22 Okt 2009) | 1 line Fix markup. ........ r75595 | georg.brandl | 2009-10-22 09:56:56 +0200 (Do, 22 Okt 2009) | 1 line Fix duplicate target. ........ r75596 | georg.brandl | 2009-10-22 10:05:04 +0200 (Do, 22 Okt 2009) | 1 line Add a new directive marking up implementation details and start using it. ........ r75600 | georg.brandl | 2009-10-22 13:01:46 +0200 (Do, 22 Okt 2009) | 1 line Make it more robust. ........ r75602 | georg.brandl | 2009-10-22 13:28:06 +0200 (Do, 22 Okt 2009) | 1 line Document new directive. ........ r75603 | georg.brandl | 2009-10-22 13:28:23 +0200 (Do, 22 Okt 2009) | 1 line Allow short form with text as argument. ........ r75604 | georg.brandl | 2009-10-22 13:36:50 +0200 (Do, 22 Okt 2009) | 1 line Fix stylesheet for multi-paragraph impl-details. ........ r75605 | georg.brandl | 2009-10-22 13:48:10 +0200 (Do, 22 Okt 2009) | 1 line Use "impl-detail" directive where applicable. ........ r75606 | georg.brandl | 2009-10-22 17:00:06 +0200 (Do, 22 Okt 2009) | 1 line #6324: membership test tries iteration via __iter__. ........ r75607 | georg.brandl | 2009-10-22 17:04:09 +0200 (Do, 22 Okt 2009) | 1 line #7088: document new functions in signal as Unix-only. ........ r75610 | georg.brandl | 2009-10-22 17:27:24 +0200 (Do, 22 Okt 2009) | 1 line Reorder __slots__ fine print and add a clarification. ........ r75611 | georg.brandl | 2009-10-22 17:42:32 +0200 (Do, 22 Okt 2009) | 1 line #7035: improve docs of the various <method>_errors() functions, and give them docstrings. ........ r75612 | georg.brandl | 2009-10-22 17:52:15 +0200 (Do, 22 Okt 2009) | 1 line #7156: document curses as Unix-only. ........ r75613 | georg.brandl | 2009-10-22 17:54:35 +0200 (Do, 22 Okt 2009) | 1 line #6977: getopt does not support optional option arguments. ........ r75616 | georg.brandl | 2009-10-22 18:17:05 +0200 (Do, 22 Okt 2009) | 1 line Add proper references. ........ r75617 | georg.brandl | 2009-10-22 18:20:55 +0200 (Do, 22 Okt 2009) | 1 line Make printout margin important. ........ r75623 | georg.brandl | 2009-10-23 10:14:44 +0200 (Fr, 23 Okt 2009) | 1 line #7188: fix optionxform() docs. ........ r75627 | fred.drake | 2009-10-23 15:04:51 +0200 (Fr, 23 Okt 2009) | 2 lines add further note about what's passed to optionxform ........ r75640 | neil.schemenauer | 2009-10-23 21:58:17 +0200 (Fr, 23 Okt 2009) | 2 lines Improve some docstrings in the 'warnings' module. ........ r75647 | georg.brandl | 2009-10-24 12:04:19 +0200 (Sa, 24 Okt 2009) | 1 line Fix markup. ........ r75696 | georg.brandl | 2009-10-25 21:25:43 +0100 (So, 25 Okt 2009) | 1 line Fix a demo. ........ r75795 | georg.brandl | 2009-10-27 16:10:22 +0100 (Di, 27 Okt 2009) | 1 line Fix a strange mis-edit. ........
2009-10-27 12:28:25 -03:00
Transforms the option name *option* as found in an input file or as passed in
by client code to the form that should be used in the internal structures.
The default implementation returns a lower-case version of *option*;
subclasses may override this or client code can set an attribute of this name
on instances to affect this behavior.
You don't necessarily need to subclass a ConfigParser to use this method, you
can also re-set it on an instance, to a function that takes a string
argument. Setting it to ``str``, for example, would make option names case
sensitive::
cfgparser = ConfigParser()
...
cfgparser.optionxform = str
Note that when reading configuration files, whitespace around the
option names are stripped before :meth:`optionxform` is called.
2007-08-15 11:28:22 -03:00
.. _configparser-objects:
ConfigParser Objects
--------------------
The :class:`ConfigParser` class extends some methods of the
:class:`RawConfigParser` interface, adding some optional arguments.
.. method:: ConfigParser.get(section, option, raw=False, vars=None)
2007-08-15 11:28:22 -03:00
Get an *option* value for the named *section*. All the ``'%'`` interpolations
are expanded in the return values, based on the defaults passed into the
constructor, as well as the options *vars* provided, unless the *raw* argument
is true.
.. method:: ConfigParser.items(section, raw=False, vars=None)
2007-08-15 11:28:22 -03:00
Return a list of ``(name, value)`` pairs for each option in the given *section*.
Optional arguments have the same meaning as for the :meth:`get` method.
.. _safeconfigparser-objects:
SafeConfigParser Objects
------------------------
The :class:`SafeConfigParser` class implements the same extended interface as
:class:`ConfigParser`, with the following addition:
.. method:: SafeConfigParser.set(section, option, value)
If the given section exists, set the given option to the specified value;
otherwise raise :exc:`NoSectionError`. *value* must be a string; if it is
not, :exc:`TypeError` is raised.
2007-08-15 11:28:22 -03:00
Examples
--------
An example of writing to a configuration file::
import configparser
config = configparser.RawConfigParser()
2009-01-03 17:18:54 -04:00
# When adding sections or items, add them in the reverse order of
# how you want them to be displayed in the actual file.
# In addition, please note that using RawConfigParser's and the raw
# mode of ConfigParser's respective set functions, you can assign
# non-string values to keys internally, but will receive an error
# when attempting to write to a file or when you get it in non-raw
# mode. SafeConfigParser does not allow such assignments to take place.
config.add_section('Section1')
config.set('Section1', 'int', '15')
config.set('Section1', 'bool', 'true')
config.set('Section1', 'float', '3.1415')
config.set('Section1', 'baz', 'fun')
config.set('Section1', 'bar', 'Python')
config.set('Section1', 'foo', '%(bar)s is %(baz)s!')
2009-01-03 17:18:54 -04:00
# Writing our configuration file to 'example.cfg'
with open('example.cfg', 'w') as configfile:
config.write(configfile)
An example of reading the configuration file again::
import configparser
config = configparser.RawConfigParser()
config.read('example.cfg')
# getfloat() raises an exception if the value is not a float
# getint() and getboolean() also do this for their respective types
float = config.getfloat('Section1', 'float')
int = config.getint('Section1', 'int')
print(float + int)
# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
# This is because we are using a RawConfigParser().
if config.getboolean('Section1', 'bool'):
print(config.get('Section1', 'foo'))
To get interpolation, you will need to use a :class:`ConfigParser` or
:class:`SafeConfigParser`::
import configparser
config = configparser.ConfigParser()
config.read('example.cfg')
# Set the third, optional argument of get to 1 if you wish to use raw mode.
print(config.get('Section1', 'foo', 0)) # -> "Python is fun!"
print(config.get('Section1', 'foo', 1)) # -> "%(bar)s is %(baz)s!"
# The optional fourth argument is a dict with members that will take
# precedence in interpolation.
print(config.get('Section1', 'foo', 0, {'bar': 'Documentation',
'baz': 'evil'}))
2009-01-03 17:18:54 -04:00
Defaults are available in all three types of ConfigParsers. They are used in
interpolation if an option used is not defined elsewhere. ::
import configparser
# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = configparser.SafeConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')
2009-01-03 17:18:54 -04:00
print(config.get('Section1', 'foo')) # -> "Python is fun!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print(config.get('Section1', 'foo')) # -> "Life is hard!"
The function ``opt_move`` below can be used to move options between sections::
def opt_move(config, section1, section2, option):
try:
config.set(section2, option, config.get(section1, option, 1))
except configparser.NoSectionError:
# Create non-existent section
config.add_section(section2)
opt_move(config, section1, section2, option)
Merged revisions 60151-60159,60161-60168,60170,60172-60173,60175 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60151 | christian.heimes | 2008-01-21 14:11:15 +0100 (Mon, 21 Jan 2008) | 1 line A bunch of header files were not listed as dependencies for object files. Changes to files like Parser/parser.h weren't picked up by make. ........ r60152 | georg.brandl | 2008-01-21 15:16:46 +0100 (Mon, 21 Jan 2008) | 3 lines #1087741: make mmap.mmap the type of mmap objects, not a factory function. Allow it to be subclassed. ........ r60153 | georg.brandl | 2008-01-21 15:18:14 +0100 (Mon, 21 Jan 2008) | 2 lines mmap is an extension module. ........ r60154 | georg.brandl | 2008-01-21 17:28:13 +0100 (Mon, 21 Jan 2008) | 2 lines Fix example. ........ r60155 | georg.brandl | 2008-01-21 17:34:07 +0100 (Mon, 21 Jan 2008) | 2 lines #1555501: document plistlib and move it to the general library. ........ r60156 | georg.brandl | 2008-01-21 17:36:00 +0100 (Mon, 21 Jan 2008) | 2 lines Add a stub for bundlebuilder documentation. ........ r60157 | georg.brandl | 2008-01-21 17:46:58 +0100 (Mon, 21 Jan 2008) | 2 lines Removing bundlebuilder docs again -- it's not to be used anymore (see #779825). ........ r60158 | georg.brandl | 2008-01-21 17:51:51 +0100 (Mon, 21 Jan 2008) | 2 lines #997912: acknowledge nested scopes in tutorial. ........ r60159 | vinay.sajip | 2008-01-21 18:02:26 +0100 (Mon, 21 Jan 2008) | 1 line Fix: #1836: Off-by-one bug in TimedRotatingFileHandler rollover calculation. Patch thanks to Kathryn M. Kowalski. ........ r60161 | georg.brandl | 2008-01-21 18:13:03 +0100 (Mon, 21 Jan 2008) | 2 lines Adapt pydoc to new doc URLs. ........ r60162 | georg.brandl | 2008-01-21 18:17:00 +0100 (Mon, 21 Jan 2008) | 2 lines Fix old link. ........ r60163 | georg.brandl | 2008-01-21 18:22:06 +0100 (Mon, 21 Jan 2008) | 2 lines #1726198: replace while 1: fp.readline() with file iteration. ........ r60164 | georg.brandl | 2008-01-21 18:29:23 +0100 (Mon, 21 Jan 2008) | 2 lines Clarify $ behavior in re docstring. #1631394. ........ r60165 | vinay.sajip | 2008-01-21 18:39:22 +0100 (Mon, 21 Jan 2008) | 1 line Minor documentation change - hyperlink tidied up. ........ r60166 | georg.brandl | 2008-01-21 18:42:40 +0100 (Mon, 21 Jan 2008) | 2 lines #1530959: change distutils build dir for --with-pydebug python builds. ........ r60167 | vinay.sajip | 2008-01-21 19:16:05 +0100 (Mon, 21 Jan 2008) | 1 line Updated to include news on recent logging fixes and documentation changes. ........ r60168 | georg.brandl | 2008-01-21 19:35:49 +0100 (Mon, 21 Jan 2008) | 3 lines Issue #1882: when compiling code from a string, encoding cookies in the second line of code were not always recognized correctly. ........ r60170 | georg.brandl | 2008-01-21 19:36:51 +0100 (Mon, 21 Jan 2008) | 2 lines Add NEWS entry for #1882. ........ r60172 | georg.brandl | 2008-01-21 19:41:24 +0100 (Mon, 21 Jan 2008) | 2 lines Use original location of document, which has translations. ........ r60173 | walter.doerwald | 2008-01-21 21:18:04 +0100 (Mon, 21 Jan 2008) | 2 lines Follow PEP 8 in module docstring. ........ r60175 | georg.brandl | 2008-01-21 21:20:53 +0100 (Mon, 21 Jan 2008) | 2 lines Adapt to latest doctools refactoring. ........
2008-01-21 16:36:10 -04:00
else:
config.remove_option(section1, option)
Some configuration files are known to include settings without values, but which
otherwise conform to the syntax supported by :mod:`configparser`. The
*allow_no_value* parameter to the constructor can be used to indicate that such
values should be accepted:
.. doctest::
>>> import configparser
>>> import io
>>> sample_config = """
... [mysqld]
... user = mysql
... pid-file = /var/run/mysqld/mysqld.pid
... skip-external-locking
... old_passwords = 1
... skip-bdb
... skip-innodb
... """
>>> config = configparser.RawConfigParser(allow_no_value=True)
>>> config.readfp(io.BytesIO(sample_config))
>>> # Settings with values are treated as before:
>>> config.get("mysqld", "user")
'mysql'
>>> # Settings without values provide None:
>>> config.get("mysqld", "skip-bdb")
>>> # Settings which aren't specified still raise an error:
>>> config.get("mysqld", "does-not-exist")
Traceback (most recent call last):
...
configparser.NoOptionError: No option 'does-not-exist' in section: 'mysqld'