configparser hype coming up!

Doc/whatsnew/3.2.rst

@@ -1220,33 +1220,20 @@ There is also a convenient command-line interface::
 
   Paths:
           data = "C:\Python32"
-          include = "C:\Python32\Include"
-          platinclude = "C:\Python32\Include"
-          platlib = "C:\Python32\Lib\site-packages"
-          platstdlib = "C:\Python32\Lib"
-          purelib = "C:\Python32\Lib\site-packages"
-          scripts = "C:\Python32\Scripts"
-          stdlib = "C:\Python32\Lib"
+          include = "C:\Python32\Include" platinclude = "C:\Python32\Include"
+          platlib = "C:\Python32\Lib\site-packages" platstdlib
+          = "C:\Python32\Lib" purelib = "C:\Python32\Lib\site-packages" scripts
+          = "C:\Python32\Scripts" stdlib = "C:\Python32\Lib"
 
   Variables:
           BINDIR = "C:\Python32"
-          BINLIBDEST = "C:\Python32\Lib"
-          EXE = ".exe"
-          INCLUDEPY = "C:\Python32\Include"
-          LIBDEST = "C:\Python32\Lib"
-          SO = ".pyd"
-          VERSION = "32"
-          abiflags = ""
-          base = "C:\Python32"
-          exec_prefix = "C:\Python32"
-          platbase = "C:\Python32"
-          prefix = "C:\Python32"
-          projectbase = "C:\Python32"
-          py_version = "3.2"
-          py_version_nodot = "32"
-          py_version_short = "3.2"
-          srcdir = "C:\Python32"
-          userbase = "C:\Documents and Settings\Raymond\Application Data\Python"
+          BINLIBDEST = "C:\Python32\Lib" EXE = ".exe" INCLUDEPY
+          = "C:\Python32\Include" LIBDEST = "C:\Python32\Lib" SO = ".pyd"
+          VERSION = "32" abiflags = "" base = "C:\Python32" exec_prefix
+          = "C:\Python32" platbase = "C:\Python32" prefix = "C:\Python32"
+          projectbase = "C:\Python32" py_version = "3.2" py_version_nodot = "32"
+          py_version_short = "3.2" srcdir = "C:\Python32" userbase
+          = "C:\Documents and Settings\Raymond\Application Data\Python"
 
 pdb
 ---
@@ -1266,8 +1253,83 @@ The :mod:`pdb` debugger module gained a number of usability improvements:
   the global and local  names found in the current scope.
 * breakpoints can be cleared by breakpoint number
 
+configparser
+------------
+
+The :mod:`configparser` module was modified to improve usability and
+predictability of the default parser and its supported INI syntax.  The old
+:class:`ConfigParser` class was removed in favor of :class:`SafeConfigParser`
+which has in turn been renamed to :class:`ConfigParser`. Support for inline
+comments is now turned off by default and section or option duplicates are not
+allowed in a single configuration source.
+
+Config parsers gained a new API based on the mapping protocol::
+
+  >>> parser = ConfigParser()
+  >>> parser.read_string("""
+  ... [DEFAULT]
+  ... monty = python
+  ...
+  ... [phrases]
+  ... the = who
+  ... full = metal jacket
+  ... """)
+  >>> parser['phrases']['full']
+  'metal jacket'
+  >>> section = parser['phrases']
+  >>> section['the']
+  'who'
+  >>> section['british'] = '%(the)s %(full)s %(monty)s!'
+  >>> parser['phrases']['british']
+  'who metal jacket python!'
+  >>> 'british' in section
+  True
+
+The new API is implemented on top of the classical API e.g. custom parser
+subclasses should be able to use it without modifications.
+
+The INI file structure accepted by config parsers can now be customized. Users
+are able to specify alternative option/value delimiters and comment prefixes,
+change the name of the DEFAULT section or switch the interpolation syntax.
+Along with support for pluggable interpolation, an additional buildout-like
+interpolation handler (ExtendedInterpolation) was introduced::
+
+  >>> parser = ConfigParser(interpolation=ExtendedInterpolation())
+  >>> parser.read_dict({'buildout': {'directory': '/home/ambv/zope9'},
+  ...                   'custom': {'prefix': '/usr/local'}})
+  >>> parser.read_string("""
+  ... [buildout]
+  ... parts =
+  ...   zope9
+  ...   instance
+  ... find-links =
+  ...   ${buildout:directory}/downloads/dist
+  ...
+  ... [zope9]
+  ... recipe = plone.recipe.zope9install
+  ... location = /opt/zope
+  ...
+  ... [instance]
+  ... recipe = plone.recipe.zope9instance
+  ... zope9-location = ${zope9:location}
+  ... zope-conf = ${custom:prefix}/etc/zope.conf
+  ... """)
+  >>> parser['buildout']['find-links']
+  '\n/home/ambv/zope9/downloads/dist'
+  >>> parser['instance']['zope-conf']
+  '/usr/local/etc/zope.conf'
+  >>> instance = parser['instance']
+  >>> instance['zope-conf']
+  '/usr/local/etc/zope.conf'
+  >>> instance['zope9-location']
+  '/opt/zope'
+
+A number of smaller features were also introduced, like support for specifying
+encoding in read operations, specifying fallback values in getters, or reading
+directly from dictionaries and strings.
+
+(All changes contributed by Łukasz Langa.)
 
-.. XXX: Various ConfigParser changes
 .. XXX: Mention urllib.parse changes
           Issue 9873 (Nick Coghlan):
             - ASCII byte sequence support in URL parsing
@@ -1541,6 +1603,34 @@ Porting to Python 3.2
 This section lists previously described changes and other bugfixes that may
 require changes to your code:
 
+* The :mod:`configparser` class :class:`SafeConfigParser` has been updated and
+  renamed to :class:`ConfigParser` whereas the old :class:`ConfigParser` class
+  has been removed. This means a couple of minor incompatibilities:
+
+  * interpolation syntax is now validated on :meth:`get` and :meth:`set`
+    operations. In the default interpolation scheme, only two tokens with
+    percent signs are valid: %(name)s and %%, the latter being an escaped
+    percent sign. If that is not welcome, consider using
+    :class:`ExtendedInterpolation` or none at all.
+
+  * :meth:`set` and :meth:`add_section` now check whether the given value type
+    is a string. :mod:`configparser` was never designed to hold non-string
+    values internally.
+
+  * exception is raised on any section or option duplicates that appear when
+    reading a single source. This exposes mistakes in user configuration.
+
+  * inline comments are now disabled by default which means the ``;`` character
+    can be safeuly used in values (``#`` was never allowed as inline comment).
+
+  * comments now can be indented which means for ``;`` and ``#`` to appear at
+    the start of a line in multiline values, it has to be interpolated. This is
+    preferable because in INI files a character that is also a comment prefix
+    cannot be taken for a comment by mistake.
+
+  * ``""`` is now a valid value, no longer automatically converted to an empty
+    string. For empty strings users can use ``"option ="`` in a line.
+
 * The :mod:`nntplib` module was reworked extensively, meaning that its APIs
   are often incompatible with the 3.1 APIs.