Changeset 391 for python/trunk/Doc/library/configparser.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/configparser.rst (modified) (11 diffs)

python/trunk/Doc/library/configparser.rst

@@ -13 +13 @@
 
    The :mod:`ConfigParser` module has been renamed to :mod:`configparser` in
-   Python 3.0.  The :term:`2to3` tool will automatically adapt imports when
-   converting your sources to 3.0.
+   Python 3.  The :term:`2to3` tool will automatically adapt imports when
+   converting your sources to Python 3.
 
 .. index::
@@ -32 +32 @@
    This library does *not* interpret or write the value-type prefixes used in
    the Windows Registry extended version of INI syntax.
+
+.. 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.
+
+   Module :mod:`json`
+      The json module implements a subset of JavaScript syntax which can also
+      be used for this purpose.
 
 The configuration file consists of sections, led by a ``[section]`` header and
@@ -42 +52 @@
 ``';'`` are ignored and may be used to provide comments.
 
+Configuration files may include comments, prefixed by specific characters (``#``
+and ``;``).  Comments may appear on their own in an otherwise empty line, or may
+be entered in lines holding values or section names.  In the latter case, they
+need to be preceded by a whitespace character to be recognized as a comment.
+(For backwards compatibility, only ``;`` starts an inline comment, while ``#``
+does not.)
+
+On top of the core functionality, :class:`SafeConfigParser` supports
+interpolation.  This means 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.
+
 For example::
 
@@ -63 +85 @@
 
 
-.. class:: RawConfigParser([defaults[, dict_type]])
+.. class:: RawConfigParser([defaults[, dict_type[, allow_no_value]]])
 
    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. This class does not
+   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
    support the magical interpolation behavior.
+
+   All option names are passed through the :meth:`optionxform` method.  Its
+   default implementation converts option names to lower case.
 
    .. versionadded:: 2.3
@@ -76 +105 @@
       *dict_type* was added.
 
-
-.. class:: ConfigParser([defaults[, dict_type]])
+   .. versionchanged:: 2.7
+      The default *dict_type* is :class:`collections.OrderedDict`.
+      *allow_no_value* was added.
+
+
+.. class:: ConfigParser([defaults[, dict_type[, allow_no_value]]])
 
    Derived class of :class:`RawConfigParser` that implements the magical
@@ -87 +120 @@
 
    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.
-
-
-.. class:: SafeConfigParser([defaults[, dict_type]])
+   :meth:`optionxform` method just like any other option name reference.  Using
+   the default implementation of :meth:`optionxform`, the values ``foo %(bar)s``
+   and ``foo %(BAR)s`` are equivalent.
+
+   .. versionadded:: 2.3
+
+   .. versionchanged:: 2.6
+      *dict_type* was added.
+
+   .. versionchanged:: 2.7
+      The default *dict_type* is :class:`collections.OrderedDict`.
+      *allow_no_value* was added.
+
+
+.. class:: SafeConfigParser([defaults[, dict_type[, allow_no_value]]])
 
    Derived class of :class:`ConfigParser` that implements a more-sane variant of
@@ -103 +144 @@
 
    .. versionadded:: 2.3
+
+   .. versionchanged:: 2.6
+      *dict_type* was added.
+
+   .. versionchanged:: 2.7
+      The default *dict_type* is :class:`collections.OrderedDict`.
+      *allow_no_value* was added.
+
+
+.. exception:: Error
+
+   Base class for all other configparser exceptions.
 
 
@@ -348 +401 @@
 .. method:: ConfigParser.get(section, option[, raw[, vars]])
 
-   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.
-
+   Get an *option* value for the named *section*.  If *vars* is provided, it
+   must be a dictionary.  The *option* is looked up in *vars* (if provided),
+   *section*, and in *defaults* in that order.
+
+   All the ``'%'`` interpolations are expanded in the return values, unless the
+   *raw* argument is true.  Values for interpolation keys are looked up in the
+   same manner as the option.
 
 .. method:: ConfigParser.items(section[, raw[, vars]])
@@ -397 +452 @@
    # 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', 'an_int', '15')
+   config.set('Section1', 'a_bool', 'true')
+   config.set('Section1', 'a_float', '3.1415')
    config.set('Section1', 'baz', 'fun')
    config.set('Section1', 'bar', 'Python')
@@ -417 +472 @@
    # 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
+   a_float = config.getfloat('Section1', 'a_float')
+   an_int = config.getint('Section1', 'an_int')
+   print a_float + an_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'):
+   if config.getboolean('Section1', 'a_bool'):
        print config.get('Section1', 'foo')
 
@@ -468 +523 @@
        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'