Merge.

11 files changed, 155 insertions, 71 deletions

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 8bd3ca5..ebc1360 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -351,18 +351,20 @@ Note that most parent parsers will specify ``add_help=False``.  Otherwise, the
 :class:`ArgumentParser` will see two ``-h/--help`` options (one in the parent
 and one in the child) and raise an error.
 
+.. note::
+   You must fully initialize the parsers before passing them via ``parents=``.
+   If you change the parent parsers after the child parser, those changes will
+   not be reflected in the child.
+
 
 formatter_class
 ^^^^^^^^^^^^^^^
 
 :class:`ArgumentParser` objects allow the help formatting to be customized by
-specifying an alternate formatting class.  Currently, there are three such
-classes: :class:`argparse.RawDescriptionHelpFormatter`,
-:class:`argparse.RawTextHelpFormatter` and
-:class:`argparse.ArgumentDefaultsHelpFormatter`.  The first two allow more
-control over how textual descriptions are displayed, while the last
-automatically adds information about argument default values.
+specifying an alternate formatting class.
 
+:class:`RawDescriptionHelpFormatter` and :class:`RawTextHelpFormatter` give
+more control over how textual descriptions are displayed.
 By default, :class:`ArgumentParser` objects line-wrap the description_ and
 epilog_ texts in command-line help messages::
 
@@ -386,7 +388,7 @@ epilog_ texts in command-line help messages::
    likewise for this epilog whose whitespace will be cleaned up and whose words
    will be wrapped across a couple lines
 
-Passing :class:`argparse.RawDescriptionHelpFormatter` as ``formatter_class=``
+Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=``
 indicates that description_ and epilog_ are already correctly formatted and
 should not be line-wrapped::
 
@@ -412,11 +414,11 @@ should not be line-wrapped::
    optional arguments:
     -h, --help  show this help message and exit
 
-:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text
+:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
 including argument descriptions.
 
-The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`,
-will add information about the default value of each of the arguments::
+:class:`ArgumentDefaultsHelpFormatter` automatically adds information about
+default values to each of the argument help messages::
 
    >>> parser = argparse.ArgumentParser(
    ...     prog='PROG',
@@ -433,6 +435,25 @@ will add information about the default value of each of the arguments::
     -h, --help  show this help message and exit
     --foo FOO   FOO! (default: 42)
 
+:class:`MetavarTypeHelpFormatter` uses the name of the type_ argument for each
+argument as as the display name for its values (rather than using the dest_
+as the regular formatter does)::
+
+   >>> parser = argparse.ArgumentParser(
+   ...     prog='PROG',
+   ...     formatter_class=argparse.MetavarTypeHelpFormatter)
+   >>> parser.add_argument('--foo', type=int)
+   >>> parser.add_argument('bar', type=float)
+   >>> parser.print_help()
+   usage: PROG [-h] [--foo int] float
+
+   positional arguments:
+     float
+
+   optional arguments:
+     -h, --help  show this help message and exit
+     --foo int
+
 
 conflict_handler
 ^^^^^^^^^^^^^^^^
@@ -1314,13 +1335,24 @@ of :data:`sys.argv`.  This can be accomplished by passing a list of strings to
    Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
 
 
-Custom namespaces
-^^^^^^^^^^^^^^^^^
+The Namespace object
+^^^^^^^^^^^^^^^^^^^^
+
+By default, :meth:`parse_args` will return a new object of type :class:`Namespace`
+where the necessary attributes have been set. This class is deliberately simple,
+just an :class:`object` subclass with a readable string representation. If you
+prefer to have dict-like view of the attributes, you can use the standard Python
+idiom via :func:`vars`::
+
+   >>> parser = argparse.ArgumentParser()
+   >>> parser.add_argument('--foo')
+   >>> args = parser.parse_args(['--foo', 'BAR'])
+   >>> vars(args)
+   {'foo': 'BAR'}
 
 It may also be useful to have an :class:`ArgumentParser` assign attributes to an
-already existing object, rather than the newly-created :class:`Namespace` object
-that is normally used.  This can be achieved by specifying the ``namespace=``
-keyword argument::
+already existing object, rather than a new :class:`Namespace` object.  This can
+be achieved by specifying the ``namespace=`` keyword argument::
 
    >>> class C:
    ...     pass
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index fc6bbbf..58354f8 100644
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -28,10 +28,10 @@ example, whether it is hashable or whether it is a mapping.
 Collections Abstract Base Classes
 ---------------------------------
 
-The collections module offers the following ABCs:
+The collections module offers the following :term:`ABCs <abstract base class>`:
 
 =========================  =====================  ======================  ====================================================
-ABC                        Inherits               Abstract Methods        Mixin Methods
+ABC                        Inherits from          Abstract Methods        Mixin Methods
 =========================  =====================  ======================  ====================================================
 :class:`Container`                                ``__contains__``
 :class:`Hashable`                                 ``__hash__``
@@ -44,15 +44,15 @@ ABC                        Inherits               Abstract Methods        Mixin
                            :class:`Iterable`,                             ``index``, and ``count``
                            :class:`Container`
 
-:class:`MutableSequence`   :class:`Sequence`      ``__setitem__``         Inherited Sequence methods and
+:class:`MutableSequence`   :class:`Sequence`      ``__setitem__``         Inherited :class:`Sequence` methods and
                                                   ``__delitem__``,        ``append``, ``reverse``, ``extend``, ``pop``,
-                                                  and ``insert``          ``remove``, ``clear``, and ``__iadd__``
+                                                  ``insert``              ``remove``, ``clear``, and ``__iadd__``
 
 :class:`Set`               :class:`Sized`,                                ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
                            :class:`Iterable`,                             ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,
                            :class:`Container`                             ``__sub__``, ``__xor__``, and ``isdisjoint``
 
-:class:`MutableSet`        :class:`Set`           ``add`` and             Inherited Set methods and
+:class:`MutableSet`        :class:`Set`           ``add``,                Inherited :class:`Set` methods and
                                                   ``discard``             ``clear``, ``pop``, ``remove``, ``__ior__``,
                                                                           ``__iand__``, ``__ixor__``, and ``__isub__``
 
@@ -60,19 +60,61 @@ ABC                        Inherits               Abstract Methods        Mixin
                            :class:`Iterable`,                             ``get``, ``__eq__``, and ``__ne__``
                            :class:`Container`
 
-:class:`MutableMapping`    :class:`Mapping`       ``__setitem__`` and     Inherited Mapping methods and
+:class:`MutableMapping`    :class:`Mapping`       ``__setitem__``,        Inherited :class:`Mapping` methods and
                                                   ``__delitem__``         ``pop``, ``popitem``, ``clear``, ``update``,
                                                                           and ``setdefault``
 
 
 :class:`MappingView`       :class:`Sized`                                 ``__len__``
-:class:`KeysView`          :class:`MappingView`,                          ``__contains__``,
-                           :class:`Set`                                   ``__iter__``
 :class:`ItemsView`         :class:`MappingView`,                          ``__contains__``,
                            :class:`Set`                                   ``__iter__``
+:class:`KeysView`          :class:`MappingView`,                          ``__contains__``,
+                           :class:`Set`                                   ``__iter__``
 :class:`ValuesView`        :class:`MappingView`                           ``__contains__``, ``__iter__``
 =========================  =====================  ======================  ====================================================
 
+
+.. class:: Container
+           Hashable
+           Sized
+           Callable
+
+   ABCs for classes that provide respectively the methods :meth:`__contains__`,
+   :meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`.
+
+.. class:: Iterable
+
+   ABC for classes that provide the :meth:`__iter__` method.
+   See also the definition of :term:`iterable`.
+
+.. class:: Iterator
+
+   ABC for classes that provide the :meth:`__iter__` and :meth:`next` methods.
+   See also the definition of :term:`iterator`.
+
+.. class:: Sequence
+           MutableSequence
+
+   ABCs for read-only and mutable :term:`sequences <sequence>`.
+
+.. class:: Set
+           MutableSet
+
+   ABCs for read-only and mutable sets.
+
+.. class:: Mapping
+           MutableMapping
+
+   ABCs for read-only and mutable :term:`mappings <mapping>`.
+
+.. class:: MappingView
+           ItemsView
+           KeysView
+           ValuesView
+
+   ABCs for mapping, items, keys, and values :term:`views <view>`.
+
+
 These ABCs allow us to ask classes or instances if they provide
 particular functionality, for example::
 
diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst
index 55dd958..cb7a09c 100644
--- a/Doc/library/compileall.rst
+++ b/Doc/library/compileall.rst
@@ -68,6 +68,9 @@ compile Python sources.
 .. versionchanged:: 3.2
    Added the ``-i``, ``-b`` and ``-h`` options.
 
+There is no command-line option to control the optimization level used by the
+:func:`compile` function, because the Python interpreter itself already
+provides the option: :program:`python -O -m compileall`.
 
 Public functions
 ----------------
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index 77a0b69..8da0d74d 100644
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -102,7 +102,7 @@ as a string. :class:`HeaderParser` has the same API as the :class:`Parser`
 class.
 
 
-.. class:: Parser(_class=email.message.Message, strict=None)
+.. class:: Parser(_class=email.message.Message)
 
    The constructor for the :class:`Parser` class takes an optional argument
    *_class*.  This must be a callable factory (such as a function or a class), and
@@ -110,13 +110,8 @@ class.
    :class:`~email.message.Message` (see :mod:`email.message`).  The factory will
    be called without arguments.
 
-   The optional *strict* flag is ignored.
-
-   .. deprecated:: 2.4
-      Because the :class:`Parser` class is a backward compatible API wrapper
-      around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is
-      effectively non-strict.  You should simply stop passing a *strict* flag to
-      the :class:`Parser` constructor.
+   .. versionchanged:: 3.2
+      Removed the *strict* argument that was deprecated in 2.4.
 
    The other public :class:`Parser` methods are:
 
diff --git a/Doc/library/http.cookiejar.rst b/Doc/library/http.cookiejar.rst
index e3af41f..9771496 100644
--- a/Doc/library/http.cookiejar.rst
+++ b/Doc/library/http.cookiejar.rst
@@ -722,7 +722,7 @@ cookies (assumes Unix/Netscape convention for location of the cookies file)::
 
    import os, http.cookiejar, urllib.request
    cj = http.cookiejar.MozillaCookieJar()
-   cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt"))
+   cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
    opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
    r = opener.open("http://example.com/")
 
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index 757823d..07378d1 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -46,7 +46,7 @@ Iterator            Arguments               Results
 ====================    ============================    =================================================   =============================================================
 Iterator                Arguments                       Results                                             Example
 ====================    ============================    =================================================   =============================================================
-:func:`accumulate`      p                               p0, p0+p1, p0+p1+p2, ...                            ``accumulate([1,2,3,4,5]) --> 1 3 6 10 15``
+:func:`accumulate`      p [,func]                       p0, p0+p1, p0+p1+p2, ...                            ``accumulate([1,2,3,4,5]) --> 1 3 6 10 15``
 :func:`chain`           p, q, ...                       p0, p1, ... plast, q0, q1, ...                      ``chain('ABC', 'DEF') --> A B C D E F``
 :func:`compress`        data, selectors                 (d[0] if s[0]), (d[1] if s[1]), ...                 ``compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F``
 :func:`dropwhile`       pred, seq                       seq[n], seq[n+1], starting when pred fails          ``dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1``
@@ -84,23 +84,46 @@ The following module functions all construct and return iterators. Some provide
 streams of infinite length, so they should only be accessed by functions or
 loops that truncate the stream.
 
-.. function:: accumulate(iterable)
+.. function:: accumulate(iterable[, func])
 
     Make an iterator that returns accumulated sums. Elements may be any addable
-    type including :class:`Decimal` or :class:`Fraction`.  Equivalent to::
+    type including :class:`Decimal` or :class:`Fraction`.  If the optional
+    *func* argument is supplied, it should be a function of two arguments
+    and it will be used instead of addition.
 
-        def accumulate(iterable):
+    Equivalent to::
+
+        def accumulate(iterable, func=operator.add):
             'Return running totals'
             # accumulate([1,2,3,4,5]) --> 1 3 6 10 15
+            # accumulate([1,2,3,4,5], operator.mul) --> 1 2 6 24 120
             it = iter(iterable)
             total = next(it)
             yield total
             for element in it:
-                total = total + element
+                total = func(total, element)
                 yield total
 
+    Uses for the *func* argument include :func:`min` for a running minimum,
+    :func:`max` for a running maximum, and :func:`operator.mul` for a running
+    product::
+
+      >>> data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]
+      >>> list(accumulate(data, operator.mul))     # running product
+      [3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]
+      >>> list(accumulate(data, max))              # running maximum
+      [3, 4, 6, 6, 6, 9, 9, 9, 9, 9]
+
+      # Amortize a 5% loan of 1000 with 4 annual payments of 90
+      >>> cashflows = [1000, -90, -90, -90, -90]
+      >>> list(accumulate(cashflows, lambda bal, pmt: bal*1.05 + pmt))
+      [1000, 960.0, 918.0, 873.9000000000001, 827.5950000000001]
+
     .. versionadded:: 3.2
 
+    .. versionchanged:: 3.3
+       Added the optional *func* parameter.
+
 .. function:: chain(*iterables)
 
    Make an iterator that returns elements from the first iterable until it is
diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst
index c667317..ab55197 100644
--- a/Doc/library/readline.rst
+++ b/Doc/library/readline.rst
@@ -196,7 +196,7 @@ normally be executed automatically during interactive sessions from the user's
 
    import os
    import readline
-   histfile = os.path.join(os.environ["HOME"], ".pyhist")
+   histfile = os.path.join(os.path.expanduser("~"), ".pyhist")
    try:
        readline.read_history_file(histfile)
    except IOError:
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index b09571f..5ecc46f 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -227,33 +227,21 @@ always available.
    The struct sequence *flags* exposes the status of command line flags. The
    attributes are read only.
 
-   +------------------------------+------------------------------------------+
-   | attribute                    | flag                                     |
-   +==============================+==========================================+
-   | :const:`debug`               | -d                                       |
-   +------------------------------+------------------------------------------+
-   | :const:`division_warning`    | -Q                                       |
-   +------------------------------+------------------------------------------+
-   | :const:`inspect`             | -i                                       |
-   +------------------------------+------------------------------------------+
-   | :const:`interactive`         | -i                                       |
-   +------------------------------+------------------------------------------+
-   | :const:`optimize`            | -O or -OO                                |
-   +------------------------------+------------------------------------------+
-   | :const:`dont_write_bytecode` | -B                                       |
-   +------------------------------+------------------------------------------+
-   | :const:`no_user_site`        | -s                                       |
-   +------------------------------+------------------------------------------+
-   | :const:`no_site`             | -S                                       |
-   +------------------------------+------------------------------------------+
-   | :const:`ignore_environment`  | -E                                       |
-   +------------------------------+------------------------------------------+
-   | :const:`verbose`             | -v                                       |
-   +------------------------------+------------------------------------------+
-   | :const:`bytes_warning`       | -b                                       |
-   +------------------------------+------------------------------------------+
-   | :const:`quiet`               | -q                                       |
-   +------------------------------+------------------------------------------+
+   ============================= =============================
+   attribute                     flag
+   ============================= =============================
+   :const:`debug`                :option:`-d`
+   :const:`inspect`              :option:`-i`
+   :const:`interactive`          :option:`-i`
+   :const:`optimize`             :option:`-O` or :option:`-OO`
+   :const:`dont_write_bytecode`  :option:`-B`
+   :const:`no_user_site`         :option:`-s`
+   :const:`no_site`              :option:`-S`
+   :const:`ignore_environment`   :option:`-E`
+   :const:`verbose`              :option:`-v`
+   :const:`bytes_warning`        :option:`-b`
+   :const:`quiet`                :option:`-q`
+   ============================= =============================
 
    .. versionchanged:: 3.2
       Added ``quiet`` attribute for the new :option:`-q` flag.
diff --git a/Doc/tutorial/interactive.rst b/Doc/tutorial/interactive.rst
index ca0cfaf..5faaf96 100644
--- a/Doc/tutorial/interactive.rst
+++ b/Doc/tutorial/interactive.rst
@@ -123,10 +123,7 @@ interpreter. ::
    # bound to the Esc key by default (you can change it - see readline docs).
    #
    # Store the file in ~/.pystartup, and set an environment variable to point
-   # to it:  "export PYTHONSTARTUP=/home/user/.pystartup" in bash.
-   #
-   # Note that PYTHONSTARTUP does *not* expand "~", so you have to put in the
-   # full path to your home directory.
+   # to it:  "export PYTHONSTARTUP=~/.pystartup" in bash.
 
    import atexit
    import os
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index 256b343..358e5be 100644
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -1499,11 +1499,11 @@ filenames:
 >>> os.fsencode(filename)
 b'Sehensw\xc3\xbcrdigkeiten'
 
-Some operating systems allow direct access to the unencoded bytes in the
+Some operating systems allow direct access to encoded bytes in the
 environment.  If so, the :attr:`os.supports_bytes_environ` constant will be
 true.
 
-For direct access to unencoded environment variables (if available),
+For direct access to encoded environment variables (if available),
 use the new :func:`os.getenvb` function or use :data:`os.environb`
 which is a bytes version of :data:`os.environ`.
 
diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst
index 7f05a84..2199f0a 100644
--- a/Doc/whatsnew/3.3.rst
+++ b/Doc/whatsnew/3.3.rst
@@ -133,3 +133,7 @@ that may require changes to your code:
    ``import site`` will not add site-specific paths to the module search
    paths.  In previous versions, it did.  See changeset for doc changes in
    various files.  Contributed by Carl Meyer with editions by Éric Araujo.
+
+.. Issue #10998: -Q command-line flags are related artifacts have been
+   removed.  Code checking sys.flags.division_warning will need updating.
+   Contributed by Éric Araujo.