merge with 3.4

16 files changed, 96 insertions, 63 deletions

diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst
index 6d57b77..1ab2d74 100644
--- a/Doc/library/cmd.rst
+++ b/Doc/library/cmd.rst
@@ -148,8 +148,8 @@ A :class:`Cmd` instance has the following methods:
    Hook method executed once when :meth:`cmdloop` is about to return. This method
    is a stub in :class:`Cmd`; it exists to be overridden by subclasses.
 
-Instances of :class:`Cmd` subclasses have some public instance variables:
 
+Instances of :class:`Cmd` subclasses have some public instance variables:
 
 .. attribute:: Cmd.prompt
 
@@ -166,6 +166,13 @@ Instances of :class:`Cmd` subclasses have some public instance variables:
    The last nonempty command prefix seen.
 
 
+.. attribute:: Cmd.cmdqueue
+
+   A list of queued input lines.  The cmdqueue list is checked in
+   :meth:`cmdloop` when new input is needed; if it is nonempty, its elements
+   will be processed in order, as if entered at the prompt.
+
+
 .. attribute:: Cmd.intro
 
    A string to issue as an intro or banner.  May be overridden by giving the
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 5f7888a..99c4311 100644
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -134,7 +134,7 @@ particular functionality, for example::
 
 Several of the ABCs are also useful as mixins that make it easier to develop
 classes supporting container APIs.  For example, to write a class supporting
-the full :class:`Set` API, it only necessary to supply the three underlying
+the full :class:`Set` API, it is only necessary to supply the three underlying
 abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
 The ABC supplies the remaining methods such as :meth:`__and__` and
 :meth:`isdisjoint`::
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index 75053a5..c21f456 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -908,7 +908,7 @@ customize a prototype instance:
     >>> janes_account = default_account._replace(owner='Jane')
 
 Enumerated constants can be implemented with named tuples, but it is simpler
-and more efficient to use a simple :class:`~enum.Enum` :
+and more efficient to use a simple :class:`~enum.Enum`:
 
     >>> Status = namedtuple('Status', 'open pending closed')._make(range(3))
     >>> Status.open, Status.pending, Status.closed
@@ -917,6 +917,9 @@ and more efficient to use a simple :class:`~enum.Enum` :
     >>> class Status(Enum):
     ...     open, pending, closed = range(3)
 
+
+.. seealso::
+
     * `Recipe for named tuple abstract base class with a metaclass mix-in
       <http://code.activestate.com/recipes/577629-namedtupleabc-abstract-base-class-mix-in-for-named/>`_
       by Jan Kaliszewski.  Besides providing an :term:`abstract base class` for
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 8a85952..588ac7c 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -1833,7 +1833,7 @@ Utility functions
 .. function:: find_msvcrt()
    :module: ctypes.util
 
-   Windows only: return the filename of the VC runtype library used by Python,
+   Windows only: return the filename of the VC runtime library used by Python,
    and by the extension modules.  If the name of the library cannot be
    determined, ``None`` is returned.
 
@@ -2335,11 +2335,6 @@ other data types containing pointer type fields.
       and so on).  Later assignments to the :attr:`_fields_` class variable will
       raise an AttributeError.
 
-      Structure and union subclass constructors accept both positional and named
-      arguments.  Positional arguments are used to initialize the fields in the
-      same order as they appear in the :attr:`_fields_` definition, named
-      arguments are used to initialize the fields with the corresponding name.
-
       It is possible to defined sub-subclasses of structure types, they inherit
       the fields of the base class plus the :attr:`_fields_` defined in the
       sub-subclass, if any.
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 74d6fcb..5892154 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -34,7 +34,8 @@ class or one of its subclasses, and not from :exc:`BaseException`.  More
 information on defining exceptions is available in the Python Tutorial under
 :ref:`tut-userexceptions`.
 
-When raising (or re-raising) an exception in an :keyword:`except` clause
+When raising (or re-raising) an exception in an :keyword:`except` or
+:keyword:`finally` clause
 :attr:`__context__` is automatically set to the last exception caught; if the
 new exception is not handled the traceback that is eventually displayed will
 include the originating exception(s) and the final exception.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 047c448..9e38d6f 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -211,7 +211,7 @@ are always available.  They are listed here in alphabetical order.
    The optional arguments *flags* and *dont_inherit* control which future
    statements (see :pep:`236`) affect the compilation of *source*.  If neither
    is present (or both are zero) the code is compiled with those future
-   statements that are in effect in the code that is calling compile.  If the
+   statements that are in effect in the code that is calling :func:`compile`.  If the
    *flags* argument is given and *dont_inherit* is not (or is zero) then the
    future statements specified by the *flags* argument are used in addition to
    those that would be used anyway. If *dont_inherit* is a non-zero integer then
@@ -232,6 +232,9 @@ are always available.  They are listed here in alphabetical order.
    This function raises :exc:`SyntaxError` if the compiled source is invalid,
    and :exc:`TypeError` if the source contains null bytes.
 
+   If you want to parse Python code into its AST representation, see
+   :func:`ast.parse`.
+
    .. note::
 
       When compiling a string with multi-line code in ``'single'`` or
@@ -540,7 +543,7 @@ are always available.  They are listed here in alphabetical order.
    effect as calling :func:`str(value) <str>`.
 
    A call to ``format(value, format_spec)`` is translated to
-   ``type(value).__format__(format_spec)`` which bypasses the instance
+   ``type(value).__format__(value, format_spec)`` which bypasses the instance
    dictionary when searching for the value's :meth:`__format__` method.  A
    :exc:`TypeError` exception is raised if the method search reaches
    :mod:`object` and the *format_spec* is non-empty, or if either the
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 2e209eb..3ac66d8 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -786,17 +786,20 @@ Classes and functions
    :func:`getargspec` or :func:`getfullargspec`.
 
    The first seven arguments are (``args``, ``varargs``, ``varkw``,
-   ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``). The
-   other five arguments are the corresponding optional formatting functions
-   that are called to turn names and values into strings. The last argument
-   is an optional function to format the sequence of arguments. For example::
+   ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``).
 
-    >>> from inspect import formatargspec, getfullargspec
-    >>> def f(a: int, b: float):
-    ...     pass
-    ...
-    >>> formatargspec(*getfullargspec(f))
-    '(a: int, b: float)'
+   The other six arguments are functions that are called to turn argument names,
+   ``*`` argument name, ``**`` argument name, default values, return annotation
+   and individual annotations into strings, respectively.
+
+   For example:
+
+   >>> from inspect import formatargspec, getfullargspec
+   >>> def f(a: int, b: float):
+   ...     pass
+   ...
+   >>> formatargspec(*getfullargspec(f))
+   '(a: int, b: float)'
 
 
 .. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])
diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst
index eebd501..6037310 100644
--- a/Doc/library/pydoc.rst
+++ b/Doc/library/pydoc.rst
@@ -20,6 +20,13 @@ The :mod:`pydoc` module automatically generates documentation from Python
 modules.  The documentation can be presented as pages of text on the console,
 served to a Web browser, or saved to HTML files.
 
+For modules, classes, functions and methods, the displayed documentation is
+derived from the docstring (i.e. the :attr:`__doc__` attribute) of the object,
+and recursively of its documentable members.  If there is no docstring,
+:mod:`pydoc` tries to obtain a description from the block of comment lines just
+above the definition of the class, function or method in the source file, or at
+the top of the module (see :func:`inspect.getcomments`).
+
 The built-in function :func:`help` invokes the online help system in the
 interactive interpreter, which uses :mod:`pydoc` to generate its documentation
 as text on the console.  The same text documentation can also be viewed from
diff --git a/Doc/library/reprlib.rst b/Doc/library/reprlib.rst
index 1c694f9..ee9a10d 100644
--- a/Doc/library/reprlib.rst
+++ b/Doc/library/reprlib.rst
@@ -156,4 +156,3 @@ for file objects could be added::
 
    aRepr = MyRepr()
    print(aRepr.repr(sys.stdin))         # prints '<stdin>'
-
diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst
index a764696..db1db3e 100644
--- a/Doc/library/runpy.rst
+++ b/Doc/library/runpy.rst
@@ -127,9 +127,6 @@ The :mod:`runpy` module provides two functions:
    supplied path, and ``__spec__``, ``__cached__``, ``__loader__`` and
    ``__package__`` will all be set to :const:`None`.
 
-   ``__spec__`` will be set to :const:`None` if the supplied path is a
-   direct path to a script (as source or as precompiled bytecode).
-
    If the supplied path is a reference to a valid sys.path entry, then
    ``__spec__`` will be set appropriately for the imported ``__main__``
    module (that is, ``__spec__.name`` will always be ``__main__``).
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 4717134..6dade30 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -482,12 +482,17 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
 
    *root_dir* and *base_dir* both default to the current directory.
 
+   If *dry_run* is true, no archive is created, but the operations that would be
+   executed are logged to *logger*.
+
    *owner* and *group* are used when creating a tar archive. By default,
    uses the current owner and group.
 
    *logger* must be an object compatible with :pep:`282`, usually an instance of
    :class:`logging.Logger`.
 
+   The *verbose* argument is currently unused.
+
    .. versionchanged:: 3.5
       Added support for the *xztar* format.
 
@@ -511,14 +516,19 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
 
 .. function:: register_archive_format(name, function, [extra_args, [description]])
 
-   Register an archiver for the format *name*. *function* is a callable that
-   will be used to invoke the archiver.
+   Register an archiver for the format *name*.
+
+   *function* is the callable that will be used to unpack archives. The callable
+   will receive the *base_name* of the file to create, followed by the
+   *base_dir* (which defaults to :data:`os.curdir`) to start archiving from.
+   Further arguments are passed as keyword arguments: *owner*, *group*,
+   *dry_run* and *logger* (as passed in :func:`make_archive`).
 
    If given, *extra_args* is a sequence of ``(name, value)`` pairs that will be
    used as extra keywords arguments when the archiver callable is used.
 
    *description* is used by :func:`get_archive_formats` which returns the
-   list of archivers. Defaults to an empty list.
+   list of archivers.  Defaults to an empty string.
 
 
 .. function:: unregister_archive_format(name)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 7572210..57fd0b1 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -269,8 +269,8 @@ the same rule. [2]_ The constructors :func:`int`, :func:`float`, and
 :func:`complex` can be used to produce numbers of a specific type.
 
 All numeric types (except complex) support the following operations, sorted by
-ascending priority (operations in the same box have the same priority; all
-numeric operations have a higher priority than comparison operations):
+ascending priority (all numeric operations have a higher priority than
+comparison operations):
 
 +---------------------+---------------------------------+---------+--------------------+
 | Operation           | Result                          | Notes   | Full documentation |
@@ -404,8 +404,7 @@ The priorities of the binary bitwise operations are all lower than the numeric
 operations and higher than the comparisons; the unary operation ``~`` has the
 same priority as the other unary numeric operations (``+`` and ``-``).
 
-This table lists the bitwise operations sorted in ascending priority
-(operations in the same box have the same priority):
+This table lists the bitwise operations sorted in ascending priority:
 
 +------------+--------------------------------+----------+
 | Operation  | Result                         | Notes    |
@@ -444,7 +443,7 @@ Additional Methods on Integer Types
 -----------------------------------
 
 The int type implements the :class:`numbers.Integral` :term:`abstract base
-class`. In addition, it provides one more method:
+class`. In addition, it provides a few more methods:
 
 .. method:: int.bit_length()
 
@@ -820,10 +819,10 @@ both mutable and immutable. The :class:`collections.abc.Sequence` ABC is
 provided to make it easier to correctly implement these operations on
 custom sequence types.
 
-This table lists the sequence operations sorted in ascending priority
-(operations in the same box have the same priority).  In the table, *s* and *t*
-are sequences of the same type, *n*, *i*, *j* and *k* are integers and *x* is
-an arbitrary object that meets any type and value restrictions imposed by *s*.
+This table lists the sequence operations sorted in ascending priority.  In the
+table, *s* and *t* are sequences of the same type, *n*, *i*, *j* and *k* are
+integers and *x* is an arbitrary object that meets any type and value
+restrictions imposed by *s*.
 
 The ``in`` and ``not in`` operations have the same priorities as the
 comparison operations. The ``+`` (concatenation) and ``*`` (repetition)
@@ -4006,8 +4005,8 @@ before the statement body is executed and exited when the statement ends:
    The exception passed in should never be reraised explicitly - instead, this
    method should return a false value to indicate that the method completed
    successfully and does not want to suppress the raised exception. This allows
-   context management code (such as ``contextlib.nested``) to easily detect whether
-   or not an :meth:`__exit__` method has actually failed.
+   context management code to easily detect whether or not an :meth:`__exit__`
+   method has actually failed.
 
 Python defines several context managers to support easy thread synchronisation,
 prompt closure of files or other objects, and simpler manipulation of the active
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index ec2e1be..12d4fbc 100644
--- a/Doc/library/struct.rst
+++ b/Doc/library/struct.rst
@@ -24,6 +24,14 @@ structs and the intended conversion to/from Python values.
    or omit implicit pad bytes, use ``standard`` size and alignment instead of
    ``native`` size and alignment: see :ref:`struct-alignment` for details.
 
+Several :mod:`struct` functions (and methods of :class:`Struct`) take a *buffer*
+argument.  This refers to objects that implement the :ref:`bufferobjects` and
+provide either a readable or read-writable buffer.  The most common types used
+for that purpose are :class:`bytes` and :class:`bytearray`, but many other types
+that can be viewed as an array of bytes implement the buffer protocol, so that
+they can be read/filled without additional copying from a :class:`bytes` object.
+
+
 Functions and Exceptions
 ------------------------
 
@@ -47,7 +55,7 @@ The module defines the following exception and functions:
 
    Pack the values *v1*, *v2*, ... according to the format string *fmt* and
    write the packed bytes into the writable buffer *buffer* starting at
-   position *offset*. Note that *offset* is a required argument.
+   position *offset*.  Note that *offset* is a required argument.
 
 
 .. function:: unpack(fmt, buffer)
diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
index 4ad7d9c..2c68377 100644
--- a/Doc/library/tempfile.rst
+++ b/Doc/library/tempfile.rst
@@ -199,7 +199,7 @@ The module defines the following user-callable items:
          >>> os.path.exists(f.name)
          False
 
-The module uses two global variables that tell it how to construct a
+The module uses a global variable that tell it how to construct a
 temporary name.  They are initialized at the first call to any of the
 functions above.  The caller may change them, but this is discouraged; use
 the appropriate function arguments, instead.
diff --git a/Doc/library/tracemalloc.rst b/Doc/library/tracemalloc.rst
index f1e2602..ee4e629 100644
--- a/Doc/library/tracemalloc.rst
+++ b/Doc/library/tracemalloc.rst
@@ -27,10 +27,10 @@ frame (1 frame). To store 25 frames at startup: set the
 
 
 Examples
-========
+--------
 
 Display the top 10
-------------------
+^^^^^^^^^^^^^^^^^^
 
 Display the 10 files allocating the most memory::
 
@@ -70,7 +70,7 @@ See :meth:`Snapshot.statistics` for more options.
 
 
 Compute differences
--------------------
+^^^^^^^^^^^^^^^^^^^
 
 Take two snapshots and display the differences::
 
@@ -114,7 +114,7 @@ the :meth:`Snapshot.dump` method to analyze the snapshot offline. Then use the
 
 
 Get the traceback of a memory block
------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Code to display the traceback of the biggest memory block::
 
@@ -179,7 +179,7 @@ loaded.
 
 
 Pretty top
-----------
+^^^^^^^^^^
 
 Code to display the 10 lines allocating the most memory with a pretty output,
 ignoring ``<frozen importlib._bootstrap>`` and ``<unknown>`` files::
@@ -249,10 +249,10 @@ See :meth:`Snapshot.statistics` for more options.
 
 
 API
-===
+---
 
 Functions
----------
+^^^^^^^^^
 
 .. function:: clear_traces()
 
@@ -356,7 +356,7 @@ Functions
 
 
 Filter
-------
+^^^^^^
 
 .. class:: Filter(inclusive: bool, filename_pattern: str, lineno: int=None, all_frames: bool=False)
 
@@ -404,7 +404,7 @@ Filter
 
 
 Frame
------
+^^^^^
 
 .. class:: Frame
 
@@ -422,7 +422,7 @@ Frame
 
 
 Snapshot
---------
+^^^^^^^^
 
 .. class:: Snapshot
 
@@ -508,7 +508,7 @@ Snapshot
 
 
 Statistic
----------
+^^^^^^^^^
 
 .. class:: Statistic
 
@@ -533,7 +533,7 @@ Statistic
 
 
 StatisticDiff
--------------
+^^^^^^^^^^^^^
 
 .. class:: StatisticDiff
 
@@ -572,7 +572,7 @@ StatisticDiff
 
 
 Trace
------
+^^^^^
 
 .. class:: Trace
 
@@ -592,7 +592,7 @@ Trace
 
 
 Traceback
----------
+^^^^^^^^^
 
 .. class:: Traceback
 
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index 44a4503..94bb731 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -481,7 +481,7 @@ the *new_callable* argument to :func:`patch`.
     .. attribute:: side_effect
 
         This can either be a function to be called when the mock is called,
-        or an exception (class or instance) to be raised.
+        an iterable or an exception (class or instance) to be raised.
 
         If you pass in a function it will be called with same arguments as the
         mock and unless the function returns the :data:`DEFAULT` singleton the
@@ -489,6 +489,11 @@ the *new_callable* argument to :func:`patch`.
         function returns :data:`DEFAULT` then the mock will return its normal
         value (from the :attr:`return_value`).
 
+        If you pass in an iterable, it is used to retrieve an iterator which
+        must yield a value on every call.  This value can either be an exception
+        instance to be raised, or a value to be returned from the call to the
+        mock (:data:`DEFAULT` handling is identical to the function case).
+
         An example of a mock that raises an exception (to test exception
         handling of an API):
 
@@ -506,11 +511,7 @@ the *new_callable* argument to :func:`patch`.
             >>> mock(), mock(), mock()
             (3, 2, 1)
 
-        The :attr:`side_effect` function is called with the same arguments as the
-        mock (so it is wise for it to take arbitrary args and keyword
-        arguments) and whatever it returns is used as the return value for
-        the call. The exception is if :attr:`side_effect` returns :data:`DEFAULT`,
-        in which case the normal :attr:`return_value` is used.
+        Using a callable:
 
             >>> mock = Mock(return_value=3)
             >>> def side_effect(*args, **kwargs):
@@ -1031,7 +1032,7 @@ patch
     used.
 
     A more powerful form of *spec* is *autospec*. If you set ``autospec=True``
-    then the mock with be created with a spec from the object being replaced.
+    then the mock will be created with a spec from the object being replaced.
     All attributes of the mock will also have the spec of the corresponding
     attribute of the object being replaced. Methods and functions being mocked
     will have their arguments checked and will raise a :exc:`TypeError` if they are