Merged revisions 83226-83227,83229-83232 via svnmerge from

svn+ssh://svn.python.org/python/branches/py3k

........
  r83226 | georg.brandl | 2010-07-29 16:17:12 +0200 (Do, 29 Jul 2010) | 1 line

  #1090076: explain the behavior of *vars* in get() better.
........
  r83227 | georg.brandl | 2010-07-29 16:23:06 +0200 (Do, 29 Jul 2010) | 1 line

  Use Py_CLEAR().
........
  r83229 | georg.brandl | 2010-07-29 16:32:22 +0200 (Do, 29 Jul 2010) | 1 line

  #9407: document configparser.Error.
........
  r83230 | georg.brandl | 2010-07-29 16:36:11 +0200 (Do, 29 Jul 2010) | 1 line

  Use correct directive and name.
........
  r83231 | georg.brandl | 2010-07-29 16:46:07 +0200 (Do, 29 Jul 2010) | 1 line

  #9397: remove mention of dbm.bsd which does not exist anymore.
........
  r83232 | georg.brandl | 2010-07-29 16:49:08 +0200 (Do, 29 Jul 2010) | 1 line

  #9388: remove ERA_YEAR which is never defined in the source code.
........

6 files changed, 39 insertions, 27 deletions

diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index 1d097f9..5ddfcd7 100644
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -35,6 +35,18 @@ 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.
 
+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 spection 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::
 
    [My Section]
@@ -100,6 +112,11 @@ write-back, as will be the keys within each section.
       The default *dict_type* is :class:`collections.OrderedDict`.
 
 
+.. exception:: Error
+
+   Base class for all other configparser exceptions.
+
+
 .. exception:: NoSectionError
 
    Exception raised when a specified section is not found.
@@ -331,10 +348,13 @@ The :class:`ConfigParser` class extends some methods of the
 
 .. method:: ConfigParser.get(section, option, raw=False, vars=None)
 
-   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=False, vars=None)
diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index b4fad45..6872d79 100644
--- a/Doc/library/dbm.rst
+++ b/Doc/library/dbm.rst
@@ -21,8 +21,8 @@ the Oracle Berkeley DB.
 .. function:: whichdb(filename)
 
    This functionattempts to guess which of the several simple database modules
-   available --- :mod:`dbm.bsd`, :mod:`dbm.gnu`, :mod:`dbm.ndbm` or
-   :mod:`dbm.dumb` --- should be used to open a given file.
+   available --- :mod:`dbm.gnu`, :mod:`dbm.ndbm` or :mod:`dbm.dumb` --- should
+   be used to open a given file.
 
    Returns one of the following values: ``None`` if the file can't be opened
    because it's unreadable or doesn't exist; the empty string (``''``) if the
@@ -227,10 +227,9 @@ Dbm objects behave like mappings (dictionaries), except that keys and values are
 always stored as bytes. Printing a ``dbm`` object doesn't print the keys and
 values, and the :meth:`items` and :meth:`values` methods are not supported.
 
-This module can be used with the "classic" ndbm interface, the BSD DB
-compatibility interface, or the GNU GDBM compatibility interface. On Unix, the
-:program:`configure` script will attempt to locate the appropriate header file
-to simplify building this module.
+This module can be used with the "classic" ndbm interface or the GNU GDBM
+compatibility interface. On Unix, the :program:`configure` script will attempt
+to locate the appropriate header file to simplify building this module.
 
 .. exception:: error
 
@@ -246,9 +245,7 @@ to simplify building this module.
 .. function:: open(filename[, flag[, mode]])
 
    Open a dbm database and return a ``dbm`` object.  The *filename* argument is the
-   name of the database file (without the :file:`.dir` or :file:`.pag` extensions;
-   note that the BSD DB implementation of the interface will append the extension
-   :file:`.db` and only create one file).
+   name of the database file (without the :file:`.dir` or :file:`.pag` extensions).
 
    The optional *flag* argument must be one of these values:
 
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index 7326712..8037bfe 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -99,7 +99,7 @@ loops that truncate the stream.
                   yield element
 
 
-.. function:: itertools.chain.from_iterable(iterable)
+.. classmethod:: chain.from_iterable(iterable)
 
    Alternate constructor for :func:`chain`.  Gets chained inputs from a
    single iterable argument that is evaluated lazily.  Equivalent to::
diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst
index b536515..b9c001f 100644
--- a/Doc/library/locale.rst
+++ b/Doc/library/locale.rst
@@ -244,10 +244,6 @@ The :mod:`locale` module defines the following exception and functions:
       specified, and therefore you should not assume knowledge of it on different
       systems.
 
-   .. data:: ERA_YEAR
-
-      Get the year in the relevant era of the locale.
-
    .. data:: ERA_D_T_FMT
 
       Get a format string for :func:`strftime` to represent dates and times in a
diff --git a/Lib/configparser.py b/Lib/configparser.py
index bfbe4cb..14ddd85 100644
--- a/Lib/configparser.py
+++ b/Lib/configparser.py
@@ -521,11 +521,12 @@ class ConfigParser(RawConfigParser):
     def get(self, section, option, raw=False, vars=None):
         """Get an option value for a given section.
 
-        All % interpolations are expanded in the return values, based on the
-        defaults passed into the constructor, unless the optional argument
-        `raw' is true.  Additional substitutions may be provided using the
-        `vars' argument, which must be a dictionary whose contents overrides
-        any pre-existing defaults.
+        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 % interpolations are expanded in the return values, unless the
+        optional argument `raw' is true.  Values for interpolation keys are
+        looked up in the same manner as the option.
 
         The section DEFAULT is special.
         """
diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
index 199f34a..028b42d 100644
--- a/Objects/unicodeobject.c
+++ b/Objects/unicodeobject.c
@@ -294,8 +294,7 @@ int unicode_resize(register PyUnicodeObject *unicode,
   reset:
     /* Reset the object caches */
     if (unicode->defenc) {
-        Py_DECREF(unicode->defenc);
-        unicode->defenc = NULL;
+        Py_CLEAR(unicode->defenc);
     }
     unicode->hash = -1;
 
@@ -414,8 +413,7 @@ void unicode_dealloc(register PyUnicodeObject *unicode)
             unicode->length = 0;
         }
         if (unicode->defenc) {
-            Py_DECREF(unicode->defenc);
-            unicode->defenc = NULL;
+            Py_CLEAR(unicode->defenc);
         }
         /* Add to free list */
         *(PyUnicodeObject **)unicode = free_list;