Merge 3.2

17 files changed, 79 insertions, 70 deletions

diff --git a/Doc/distutils/install.rst b/Doc/distutils/install.rst
index 171ef98..9d916d3 100644
--- a/Doc/distutils/install.rst
+++ b/Doc/distutils/install.rst
@@ -101,8 +101,8 @@ one command from a terminal::
 
    python setup.py install
 
-For Windows, this command should be run from a command prompt windows ("DOS
-box")::
+For Windows, this command should be run from a command prompt windows
+(:menuselection:`Start --> Accessories`)::
 
    setup.py install
 
@@ -144,7 +144,7 @@ archive file to :file:`C:\\Temp`, then it would unpack into
 :file:`C:\\Temp\\foo-1.0`; you can use either a archive manipulator with a
 graphical user interface (such as WinZip) or a command-line tool (such as
 :program:`unzip` or :program:`pkunzip`) to unpack the archive.  Then, open a
-command prompt window ("DOS box"), and run::
+command prompt window and run::
 
    cd c:\Temp\foo-1.0
    python setup.py install
diff --git a/Doc/distutils/introduction.rst b/Doc/distutils/introduction.rst
index 57d34a4..0ece646 100644
--- a/Doc/distutils/introduction.rst
+++ b/Doc/distutils/introduction.rst
@@ -84,8 +84,8 @@ terminal::
 
    python setup.py sdist
 
-For Windows, open a command prompt windows ("DOS box") and change the command
-to::
+For Windows, open a command prompt window (:menuselection:`Start -->
+Accessories`) and change the command to::
 
    setup.py sdist
 
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 6984bf2..358f40e 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -163,8 +163,8 @@ Glossary
       well-designed code improves its flexibility by allowing polymorphic
       substitution.  Duck-typing avoids tests using :func:`type` or
       :func:`isinstance`.  (Note, however, that duck-typing can be complemented
-      with :term:`abstract base class`\ es.)  Instead, it typically employs
-      :func:`hasattr` tests or :term:`EAFP` programming.
+      with :term:`abstract base classes <abstract base class>`.)  Instead, it
+      typically employs :func:`hasattr` tests or :term:`EAFP` programming.
 
    EAFP
       Easier to ask for forgiveness than permission.  This common Python coding
diff --git a/Doc/install/install.rst b/Doc/install/install.rst
index a24b764..33f3e9c 100644
--- a/Doc/install/install.rst
+++ b/Doc/install/install.rst
@@ -119,12 +119,9 @@ command::
 
    pysetup run install_dist
 
-How you actually run this command depends on the platform and the command line
-interface it provides:
-
-* **Unix**: Use a shell prompt.
-* **Windows**: Open a command prompt ("DOS console") or use :command:`Powershell`.
-* **OS X**: Open a :command:`Terminal`.
+This is a command that should be run in a terminal.  On Windows, it is called a
+command prompt and found in :menuselection:`Start --> Accessories`; Powershell
+is a popular alternative.
 
 
 .. _packaging-platform-variations:
@@ -147,8 +144,7 @@ archive file to :file:`C:\\Temp`, then it would unpack into
 :file:`C:\\Temp\\foo-1.0`. To actually unpack the archive, you can use either
 an archive manipulator with a graphical user interface (such as WinZip or 7-Zip)
 or a command-line tool (such as :program:`unzip`, :program:`pkunzip` or, again,
-:program:`7z`). Then, open a command prompt window ("DOS box" or
-Powershell), and run::
+:program:`7z`). Then, open a command prompt window and run::
 
    cd c:\Temp\foo-1.0
    pysetup run install_dist
@@ -279,7 +275,8 @@ different recipe for each platform. Under Unix, just type :command:`python` at
 the shell prompt. Under Windows (assuming the Python executable is on your
 :envvar:`PATH`, which is the usual case), you can choose :menuselection:`Start --> Run`,
 type ``python`` and press ``enter``. Alternatively, you can simply execute
-:command:`python` at a command prompt ("DOS console" or Powershell).
+:command:`python` at a command prompt (:menuselection:`Start --> Accessories`)
+or in Powershell.
 
 Once the interpreter is started, you type Python code at the prompt. For
 example, on my Linux system, I type the three Python statements shown below,
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 11f87fc..af40888 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -6,10 +6,10 @@
 .. moduleauthor:: Steven Bethard <steven.bethard@gmail.com>
 .. sectionauthor:: Steven Bethard <steven.bethard@gmail.com>
 
-**Source code:** :source:`Lib/argparse.py`
-
 .. versionadded:: 3.2
 
+**Source code:** :source:`Lib/argparse.py`
+
 --------------
 
 The :mod:`argparse` module makes it easy to write user-friendly command-line
@@ -109,7 +109,7 @@ Parsing arguments
 
 :class:`ArgumentParser` parses arguments through the
 :meth:`~ArgumentParser.parse_args` method.  This will inspect the command line,
-convert each arg to the appropriate type and then invoke the appropriate action.
+convert each argument to the appropriate type and then invoke the appropriate action.
 In most cases, this means a simple :class:`Namespace` object will be built up from
 attributes parsed out of the command line::
 
@@ -244,7 +244,7 @@ This can be achieved by passing ``False`` as the ``add_help=`` argument to
     --foo FOO  foo help
 
 The help option is typically ``-h/--help``. The exception to this is
-if the ``prefix_chars=`` is specified and does not include ``'-'``, in
+if the ``prefix_chars=`` is specified and does not include ``-``, in
 which case ``-h`` and ``--help`` are not valid options.  In
 this case, the first character in ``prefix_chars`` is used to prefix
 the help options::
@@ -260,7 +260,7 @@ the help options::
 prefix_chars
 ^^^^^^^^^^^^
 
-Most command-line options will use ``'-'`` as the prefix, e.g. ``-f/--foo``.
+Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
 Parsers that need to support different or additional prefix
 characters, e.g. for options
 like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
@@ -273,7 +273,7 @@ to the ArgumentParser constructor::
    Namespace(bar='Y', f='X')
 
 The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of
-characters that does not include ``'-'`` will cause ``-f/--foo`` options to be
+characters that does not include ``-`` will cause ``-f/--foo`` options to be
 disallowed.
 
 
@@ -778,7 +778,7 @@ single action to be taken.  The ``nargs`` keyword argument associates a
 different number of command-line arguments with a single action.  The supported
 values are:
 
-* N (an integer).  N arguments from the command line will be gathered together into a
+* ``N`` (an integer).  ``N`` arguments from the command line will be gathered together into a
   list.  For example::
 
      >>> parser = argparse.ArgumentParser()
@@ -790,11 +790,11 @@ values are:
   Note that ``nargs=1`` produces a list of one item.  This is different from
   the default, in which the item is produced by itself.
 
-* ``'?'``. One arg will be consumed from the command line if possible, and
-  produced as a single item.  If no command-line arg is present, the value from
+* ``'?'``. One argument will be consumed from the command line if possible, and
+  produced as a single item.  If no command-line argument is present, the value from
   default_ will be produced.  Note that for optional arguments, there is an
   additional case - the option string is present but not followed by a
-  command-line arg.  In this case the value from const_ will be produced.  Some
+  command-line argument.  In this case the value from const_ will be produced.  Some
   examples to illustrate this::
 
      >>> parser = argparse.ArgumentParser()
@@ -836,7 +836,7 @@ values are:
 
 * ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
   list.  Additionally, an error message will be generated if there wasn't at
-  least one command-line arg present.  For example::
+  least one command-line argument present.  For example::
 
      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('foo', nargs='+')
@@ -847,7 +847,7 @@ values are:
      PROG: error: too few arguments
 
 If the ``nargs`` keyword argument is not provided, the number of arguments consumed
-is determined by the action_.  Generally this means a single command-line arg
+is determined by the action_.  Generally this means a single command-line argument
 will be consumed and a single item (not a list) will be produced.
 
 
@@ -866,7 +866,7 @@ the various :class:`ArgumentParser` actions.  The two most common uses of it are
   (like ``-f`` or ``--foo``) and ``nargs='?'``.  This creates an optional
   argument that can be followed by zero or one command-line arguments.
   When parsing the command line, if the option string is encountered with no
-  command-line arg following it, the value of ``const`` will be assumed instead.
+  command-line argument following it, the value of ``const`` will be assumed instead.
   See the nargs_ description for examples.
 
 The ``const`` keyword argument defaults to ``None``.
@@ -878,7 +878,7 @@ default
 All optional arguments and some positional arguments may be omitted at the
 command line.  The ``default`` keyword argument of
 :meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``,
-specifies what value should be used if the command-line arg is not present.
+specifies what value should be used if the command-line argument is not present.
 For optional arguments, the ``default`` value is used when the option string
 was not present at the command line::
 
@@ -889,8 +889,8 @@ was not present at the command line::
    >>> parser.parse_args(''.split())
    Namespace(foo=42)
 
-For positional arguments with nargs_ ``='?'`` or ``'*'``, the ``default`` value
-is used when no command-line arg was present::
+For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value
+is used when no command-line argument was present::
 
    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('foo', nargs='?', default=42)
@@ -976,8 +976,8 @@ choices
 Some command-line arguments should be selected from a restricted set of values.
 These can be handled by passing a container object as the ``choices`` keyword
 argument to :meth:`~ArgumentParser.add_argument`.  When the command line is
-parsed, arg values will be checked, and an error message will be displayed if
-the arg was not one of the acceptable values::
+parsed, argument values will be checked, and an error message will be displayed if
+the argument was not one of the acceptable values::
 
    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('foo', choices='abc')
@@ -1080,7 +1080,7 @@ value as the "name" of each object.  By default, for positional argument
 actions, the dest_ value is used directly, and for optional argument actions,
 the dest_ value is uppercased.  So, a single positional argument with
 ``dest='bar'`` will that argument will be referred to as ``bar``. A single
-optional argument ``--foo`` that should be followed by a single command-line arg
+optional argument ``--foo`` that should be followed by a single command-line argument
 will be referred to as ``FOO``.  An example::
 
    >>> parser = argparse.ArgumentParser()
@@ -1152,10 +1152,10 @@ attribute is determined by the ``dest`` keyword argument of
 
 For optional argument actions, the value of ``dest`` is normally inferred from
 the option strings.  :class:`ArgumentParser` generates the value of ``dest`` by
-taking the first long option string and stripping away the initial ``'--'``
+taking the first long option string and stripping away the initial ``--``
 string.  If no long option strings were supplied, ``dest`` will be derived from
-the first short option string by stripping the initial ``'-'`` character.  Any
-internal ``'-'`` characters will be converted to ``'_'`` characters to make sure
+the first short option string by stripping the initial ``-`` character.  Any
+internal ``-`` characters will be converted to ``_`` characters to make sure
 the string is a valid attribute name.  The examples below illustrate this
 behavior::
 
@@ -1187,7 +1187,7 @@ The parse_args() method
    created and how they are assigned. See the documentation for
    :meth:`add_argument` for details.
 
-   By default, the arg strings are taken from :data:`sys.argv`, and a new empty
+   By default, the argument strings are taken from :data:`sys.argv`, and a new empty
    :class:`Namespace` object is created for the attributes.
 
 
@@ -1258,15 +1258,15 @@ it exits and prints the error along with a usage message::
    PROG: error: extra arguments found: badger
 
 
-Arguments containing ``"-"``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Arguments containing ``-``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The :meth:`~ArgumentParser.parse_args` method attempts to give errors whenever
 the user has clearly made a mistake, but some situations are inherently
-ambiguous.  For example, the command-line arg ``'-1'`` could either be an
+ambiguous.  For example, the command-line argument ``-1`` could either be an
 attempt to specify an option or an attempt to provide a positional argument.
 The :meth:`~ArgumentParser.parse_args` method is cautious here: positional
-arguments may only begin with ``'-'`` if they look like negative numbers and
+arguments may only begin with ``-`` if they look like negative numbers and
 there are no options in the parser that look like negative numbers::
 
    >>> parser = argparse.ArgumentParser(prog='PROG')
@@ -1299,7 +1299,7 @@ there are no options in the parser that look like negative numbers::
    usage: PROG [-h] [-1 ONE] [foo]
    PROG: error: argument -1: expected one argument
 
-If you have positional arguments that must begin with ``'-'`` and don't look
+If you have positional arguments that must begin with ``-`` and don't look
 like negative numbers, you can insert the pseudo-argument ``'--'`` which tells
 :meth:`~ArgumentParser.parse_args` that everything after that is a positional
 argument::
@@ -1417,7 +1417,7 @@ Sub-commands
      >>> parser_b = subparsers.add_parser('b', help='b help')
      >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
      >>>
-     >>> # parse some arg lists
+     >>> # parse some argument lists
      >>> parser.parse_args(['a', '12'])
      Namespace(bar=12, foo=False)
      >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
@@ -1426,8 +1426,8 @@ Sub-commands
    Note that the object returned by :meth:`parse_args` will only contain
    attributes for the main parser and the subparser that was selected by the
    command line (and not any other subparsers).  So in the example above, when
-   the ``"a"`` command is specified, only the ``foo`` and ``bar`` attributes are
-   present, and when the ``"b"`` command is specified, only the ``foo`` and
+   the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are
+   present, and when the ``b`` command is specified, only the ``foo`` and
    ``baz`` attributes are present.
 
    Similarly, when a help message is requested from a subparser, only the help
diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst
index 8d79a1d..15b55e8 100644
--- a/Doc/library/atexit.rst
+++ b/Doc/library/atexit.rst
@@ -6,6 +6,9 @@
 .. moduleauthor:: Skip Montanaro <skip@pobox.com>
 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
+**Source code:** :source:`Lib/atexit.py`
+
+--------------
 
 The :mod:`atexit` module defines functions to register and unregister cleanup
 functions.  Functions thus registered are automatically executed upon normal
diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst
index d45c0e7..c1cda5b 100644
--- a/Doc/library/cmd.rst
+++ b/Doc/library/cmd.rst
@@ -205,6 +205,9 @@ Instances of :class:`Cmd` subclasses have some public instance variables:
    :mod:`readline`, on systems that support it, the interpreter will automatically
    support :program:`Emacs`\ -like line editing  and command-history keystrokes.)
 
+
+.. _cmd-example:
+
 Cmd Example
 -----------
 
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index 14ccffb..768519e 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -1,4 +1,3 @@
-
 :mod:`collections` --- Container datatypes
 ==========================================
 
@@ -977,7 +976,7 @@ original insertion position is changed and moved to the end::
                 del self[key]
             OrderedDict.__setitem__(self, key, value)
 
-An ordered dictionary can combined with the :class:`Counter` class
+An ordered dictionary can be combined with the :class:`Counter` class
 so that the counter remembers the order elements are first encountered::
 
    class OrderedCounter(Counter, OrderedDict):
diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
index 3bd4531..f401f93 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/Doc/library/concurrent.futures.rst
@@ -4,11 +4,11 @@
 .. module:: concurrent.futures
    :synopsis: Execute computations concurrently using threads or processes.
 
+.. versionadded:: 3.2
+
 **Source code:** :source:`Lib/concurrent/futures/thread.py`
 and :source:`Lib/concurrent/futures/process.py`
 
-.. versionadded:: 3.2
-
 --------------
 
 The :mod:`concurrent.futures` module provides a high-level interface for
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index edff106..3b6fdc3 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -624,7 +624,8 @@ are always available.  They are listed here in alphabetical order.
 .. function:: isinstance(object, classinfo)
 
    Return true if the *object* argument is an instance of the *classinfo*
-   argument, or of a (direct or indirect) subclass thereof.  If *object* is not
+   argument, or of a (direct, indirect or :term:`virtual <abstract base
+   class>`) subclass thereof.  If *object* is not
    an object of the given type, the function always returns false.  If
    *classinfo* is not a class (type object), it may be a tuple of type objects,
    or may recursively contain other such tuples (other sequence types are not
@@ -634,7 +635,8 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: issubclass(class, classinfo)
 
-   Return true if *class* is a subclass (direct or indirect) of *classinfo*.  A
+   Return true if *class* is a subclass (direct, indirect or :term:`virtual
+   <abstract base class>`) of *classinfo*.  A
    class is considered a subclass of itself. *classinfo* may be a tuple of class
    objects, in which case every entry in *classinfo* will be checked. In any other
    case, a :exc:`TypeError` exception is raised.
diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
index 27d2efd..3911d4d 100644
--- a/Doc/library/logging.handlers.rst
+++ b/Doc/library/logging.handlers.rst
@@ -799,7 +799,7 @@ possible, while any potentially slow operations (such as sending an email via
 
 
 
-.. queue-listener:
+.. _queue-listener:
 
 QueueListener
 ^^^^^^^^^^^^^
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index fddc1fb..7d2d91b 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -7,14 +7,14 @@
 .. moduleauthor:: Greg Ward <gward@python.net>
 .. sectionauthor:: Greg Ward <gward@python.net>
 
+.. deprecated:: 3.2
+  The :mod:`optparse` module is deprecated and will not be developed further;
+  development will continue with the :mod:`argparse` module.
+
 **Source code:** :source:`Lib/optparse.py`
 
 --------------
 
-.. deprecated:: 2.7
-  The :mod:`optparse` module is deprecated and will not be developed further;
-  development will continue with the :mod:`argparse` module.
-
 :mod:`optparse` is a more convenient, flexible, and powerful library for parsing
 command-line options than the old :mod:`getopt` module.  :mod:`optparse` uses a
 more declarative style of command-line parsing: you create an instance of
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 3f9ec0b..2443180 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -4,6 +4,9 @@
 .. module:: string
    :synopsis: Common string operations.
 
+**Source code:** :source:`Lib/string.py`
+
+--------------
 
 .. seealso::
 
@@ -11,10 +14,6 @@
 
    :ref:`string-methods`
 
-**Source code:** :source:`Lib/string.py`
-
---------------
-
 String constants
 ----------------
 
diff --git a/Doc/library/sysconfig.rst b/Doc/library/sysconfig.rst
index 1e89bd0..5b2509a 100644
--- a/Doc/library/sysconfig.rst
+++ b/Doc/library/sysconfig.rst
@@ -3,15 +3,16 @@
 
 .. module:: sysconfig
    :synopsis: Python's configuration information
-.. moduleauthor:: Tarek Ziade <tarek@ziade.org>
-.. sectionauthor:: Tarek Ziade <tarek@ziade.org>
+.. moduleauthor:: Tarek Ziadé <tarek@ziade.org>
+.. sectionauthor:: Tarek Ziadé <tarek@ziade.org>
+
 .. index::
    single: configuration information
 
-**Source code:** :source:`Lib/sysconfig.py`
-
 .. versionadded:: 3.2
 
+**Source code:** :source:`Lib/sysconfig.py`
+
 --------------
 
 The :mod:`sysconfig` module provides access to Python's configuration
diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
index c77a679..aece714 100644
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@ -12,6 +12,10 @@
    pair: URL; parsing
    pair: relative; URL
 
+**Source code:** :source:`Lib/urllib/parse.py`
+
+--------------
+
 This module defines a standard interface to break Uniform Resource Locator (URL)
 strings up in components (addressing scheme, network location, path etc.), to
 combine the components back into a URL string, and to convert a "relative URL"
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 3282054..019a894 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -30,15 +30,16 @@ The module defines the following items:
 
 .. exception:: BadZipFile
 
-   The error raised for bad ZIP files (old name: ``zipfile.error``).
+   The error raised for bad ZIP files.
 
    .. versionadded:: 3.2
 
 
 .. exception:: BadZipfile
 
-   This is an alias for :exc:`BadZipFile` that exists for compatibility with
-   Python versions prior to 3.2.  Usage is deprecated.
+   Alias of :exc:`BadZipFile`, for compatibility with older Python versions.
+
+   .. deprecated:: 3.2
 
 
 .. exception:: LargeZipFile
diff --git a/Lib/shutil.py b/Lib/shutil.py
index 8718884..9ba602f1 100644
--- a/Lib/shutil.py
+++ b/Lib/shutil.py
@@ -399,7 +399,7 @@ def _make_tarball(base_name, base_dir, compress="gzip", verbose=0, dry_run=0,
 
     if not os.path.exists(archive_dir):
         if logger is not None:
-            logger.info("creating %s" % archive_dir)
+            logger.info("creating %s", archive_dir)
         if not dry_run:
             os.makedirs(archive_dir)