100% test coverage, better mapping protocol compatibility, some minor bugfixes

1 files changed, 26 insertions, 16 deletions

diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index 9472b88..d0d159b 100644
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -391,17 +391,20 @@ However, there are a few differences that should be taken into account:
 
 * Trying to delete the ``DEFAULTSECT`` raises ``ValueError``.
 
-* There are two parser-level methods in the legacy API that hide the dictionary
-  interface and are incompatible:
+* ``parser.get(section, option, **kwargs)`` - the second argument is **not**
+  a fallback value. Note however that the section-level ``get()`` methods are
+  compatible both with the mapping protocol and the classic configparser API.
 
-  * ``parser.get(section, option, **kwargs)`` - the second argument is **not** a
-    fallback value
-
-  * ``parser.items(section)`` - this returns a list of *option*, *value* pairs
-    for a specified ``section``
+* ``parser.items()`` is compatible with the mapping protocol (returns a list of
+  *section_name*, *section_proxy* pairs including the DEFAULTSECT).  However,
+  this method can also be invoked with arguments: ``parser.items(section, raw,
+  vars)``. The latter call returns a list of *option*, *value* pairs for
+  a specified ``section``, with all interpolations expanded (unless
+  ``raw=True`` is provided).
 
 The mapping protocol is implemented on top of the existing legacy API so that
-subclassing the original interface makes the mappings work as expected as well.
+subclasses overriding the original interface still should have mappings working
+as expected.
 
 
 Customizing Parser Behaviour
@@ -906,7 +909,8 @@ ConfigParser Objects
    .. method:: has_option(section, option)
 
       If the given *section* exists, and contains the given *option*, return
-      :const:`True`; otherwise return :const:`False`.
+      :const:`True`; otherwise return :const:`False`. If the specified
+      *section* is :const:`None` or an empty string, DEFAULT is assumed.
 
 
    .. method:: read(filenames, encoding=None)
@@ -964,14 +968,17 @@ ConfigParser Objects
 
    .. method:: read_dict(dictionary, source='<dict>')
 
-      Load configuration from a dictionary.  Keys are section names, values are
-      dictionaries with keys and values that should be present in the section.
-      If the used dictionary type preserves order, sections and their keys will
-      be added in order.  Values are automatically converted to strings.
+      Load configuration from any object that provides a dict-like ``items()``
+      method.  Keys are section names, values are dictionaries with keys and
+      values that should be present in the section.  If the used dictionary
+      type preserves order, sections and their keys will be added in order.
+      Values are automatically converted to strings.
 
       Optional argument *source* specifies a context-specific name of the
       dictionary passed.  If not given, ``<dict>`` is used.
 
+      This method can be used to copy state between parsers.
+
       .. versionadded:: 3.2
 
 
@@ -1019,10 +1026,13 @@ ConfigParser Objects
       *fallback*.
 
 
-   .. method:: items(section, raw=False, vars=None)
+   .. method:: items([section], raw=False, vars=None)
+
+      When *section* is not given, return a list of *section_name*,
+      *section_proxy* pairs, including DEFAULTSECT.
 
-      Return a list of *name*, *value* pairs for the options in the given
-      *section*.  Optional arguments have the same meaning as for the
+      Otherwise, return a list of *name*, *value* pairs for the options in the
+      given *section*.  Optional arguments have the same meaning as for the
       :meth:`get` method.