Issue #21906: Merge from 3.4.

Author: berkerpeksag

.hgignore

@@ -18,6 +18,7 @@ db_home
 platform$
 pyconfig.h$
 python$
+python.bat$
 python.exe$
 python-config$
 python-config.py$

.hgtouch

@@ -4,6 +4,8 @@
 
 Python/importlib.h: Lib/importlib/_bootstrap.py Modules/_freeze_importlib.c
 
+Include/opcode.h:  Lib/opcode.py Tools/scripts/generate_opcode_h.py
+
 Include/Python-ast.h: Parser/Python.asdl Parser/asdl.py Parser/asdl_c.py
 Python/Python-ast.c: Include/Python-ast.h
 

Doc/README.txt

@@ -3,7 +3,7 @@ Python Documentation README
 
 This directory contains the reStructuredText (reST) sources to the Python
 documentation.  You don't need to build them yourself, prebuilt versions are
-available at <https://docs.python.org/3.4/download.html>.
+available at <https://docs.python.org/dev/download.html>.
 
 Documentation on authoring Python documentation, including information about
 both style and markup, is available in the "Documenting Python" chapter of the

Doc/c-api/memory.rst

@@ -92,8 +92,8 @@ functions are thread-safe, the :term:`GIL <global interpreter lock>` does not
 need to be held.
 
 The default raw memory block allocator uses the following functions:
-:c:func:`malloc`, :c:func:`realloc` and :c:func:`free`; call ``malloc(1)`` when
-requesting zero bytes.
+:c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`; call
+``malloc(1)`` (or ``calloc(1, 1)``) when requesting zero bytes.
 
 .. versionadded:: 3.4
 
@@ -106,6 +106,17 @@ requesting zero bytes.
    been initialized in any way.
 
 
+.. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+   request fails. The memory is initialized to zeros. Requesting zero elements
+   or elements of size zero bytes returns a distinct non-*NULL* pointer if
+   possible, as if ``PyMem_RawCalloc(1, 1)`` had been called instead.
+
+   .. versionadded:: 3.5
+
+
 .. c:function:: void* PyMem_RawRealloc(void *p, size_t n)
 
    Resizes the memory block pointed to by *p* to *n* bytes. The contents will
@@ -136,8 +147,8 @@ behavior when requesting zero bytes, are available for allocating and releasing
 memory from the Python heap.
 
 The default memory block allocator uses the following functions:
-:c:func:`malloc`, :c:func:`realloc` and :c:func:`free`; call ``malloc(1)`` when
-requesting zero bytes.
+:c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`; call
+``malloc(1)`` (or ``calloc(1, 1)``) when requesting zero bytes.
 
 .. warning::
 
@@ -152,6 +163,17 @@ requesting zero bytes.
    been called instead. The memory will not have been initialized in any way.
 
 
+.. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+   request fails. The memory is initialized to zeros. Requesting zero elements
+   or elements of size zero bytes returns a distinct non-*NULL* pointer if
+   possible, as if ``PyMem_Calloc(1, 1)`` had been called instead.
+
+   .. versionadded:: 3.5
+
+
 .. c:function:: void* PyMem_Realloc(void *p, size_t n)
 
    Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
@@ -210,7 +232,7 @@ Customize Memory Allocators
 
 .. versionadded:: 3.4
 
-.. c:type:: PyMemAllocator
+.. c:type:: PyMemAllocatorEx
 
    Structure used to describe a memory block allocator. The structure has
    four fields:
@@ -222,11 +244,19 @@ Customize Memory Allocators
    +----------------------------------------------------------+---------------------------------------+
    | ``void* malloc(void *ctx, size_t size)``                 | allocate a memory block               |
    +----------------------------------------------------------+---------------------------------------+
+   | ``void* calloc(void *ctx, size_t nelem, size_t elsize)`` | allocate a memory block initialized   |
+   |                                                          | with zeros                            |
+   +----------------------------------------------------------+---------------------------------------+
    | ``void* realloc(void *ctx, void *ptr, size_t new_size)`` | allocate or resize a memory block     |
    +----------------------------------------------------------+---------------------------------------+
    | ``void free(void *ctx, void *ptr)``                      | free a memory block                   |
    +----------------------------------------------------------+---------------------------------------+
 
+   .. versionchanged:: 3.5
+      The :c:type:`PyMemAllocator` structure was renamed to
+      :c:type:`PyMemAllocatorEx` and a new ``calloc`` field was added.
+
+
 .. c:type:: PyMemAllocatorDomain
 
    Enum used to identify an allocator domain. Domains:
@@ -239,12 +269,12 @@ Customize Memory Allocators
      :c:func:`PyObject_Realloc` and :c:func:`PyObject_Free`
 
 
-.. c:function:: void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocator *allocator)
+.. c:function:: void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
 
    Get the memory block allocator of the specified domain.
 
 
-.. c:function:: void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocator *allocator)
+.. c:function:: void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
 
    Set the memory block allocator of the specified domain.
 

Doc/c-api/number.rst

@@ -30,6 +30,14 @@ Number Protocol
    the equivalent of the Python expression ``o1 * o2``.
 
 
+.. c:function:: PyObject* PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 @ o2``.
+
+   .. versionadded:: 3.5
+
+
 .. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
 
    Return the floor of *o1* divided by *o2*, or *NULL* on failure.  This is
@@ -146,6 +154,15 @@ Number Protocol
    the Python statement ``o1 *= o2``.
 
 
+.. c:function:: PyObject* PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is
+   the equivalent of the Python statement ``o1 @= o2``.
+
+   .. versionadded:: 3.5
+
+
 .. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
 
    Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.

Doc/c-api/typeobj.rst

@@ -1141,6 +1141,9 @@ Number Object Structures
             binaryfunc nb_inplace_true_divide;
 
             unaryfunc nb_index;
+
+            binaryfunc nb_matrix_multiply;
+            binaryfunc nb_inplace_matrix_multiply;
        } PyNumberMethods;
 
    .. note::

Doc/distutils/apiref.rst

@@ -1099,13 +1099,13 @@ other utility module.
    during the build of Python), not the OS version of the current system.
 
    For universal binary builds on Mac OS X the architecture value reflects
-   the univeral binary status instead of the architecture of the current
+   the universal binary status instead of the architecture of the current
    processor. For 32-bit universal binaries the architecture is ``fat``,
    for 64-bit universal binaries the architecture is ``fat64``, and
    for 4-way universal binaries the architecture is ``universal``. Starting
    from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for
    a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for
-   a univeral build with the i386 and x86_64 architectures
+   a universal build with the i386 and x86_64 architectures
 
    Examples of returned values on Mac OS X:
 

Doc/distutils/builtdist.rst

@@ -355,7 +355,7 @@ support this option, so the command::
 would create a 64bit installation executable on your 32bit version of Windows.
 
 To cross-compile, you must download the Python source code and cross-compile
-Python itself for the platform you are targetting - it is not possible from a
+Python itself for the platform you are targeting - it is not possible from a
 binary installation of Python (as the .lib etc file for other platforms are
 not included.)  In practice, this means the user of a 32 bit operating
 system will need to use Visual Studio 2008 to open the

Doc/glossary.rst

@@ -444,12 +444,13 @@ Glossary
 
       A number of tools in Python accept key functions to control how elements
       are ordered or grouped.  They include :func:`min`, :func:`max`,
-      :func:`sorted`, :meth:`list.sort`, :func:`heapq.nsmallest`,
-      :func:`heapq.nlargest`, and :func:`itertools.groupby`.
+      :func:`sorted`, :meth:`list.sort`, :func:`heapq.merge`,
+      :func:`heapq.nsmallest`, :func:`heapq.nlargest`, and
+      :func:`itertools.groupby`.
 
       There are several ways to create a key function.  For example. the
       :meth:`str.lower` method can serve as a key function for case insensitive
-      sorts.  Alternatively, an ad-hoc key function can be built from a
+      sorts.  Alternatively, a key function can be built from a
       :keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``.  Also,
       the :mod:`operator` module provides three key function constructors:
       :func:`~operator.attrgetter`, :func:`~operator.itemgetter`, and

Doc/howto/clinic.rst

@@ -886,7 +886,7 @@ Argument Clinic generates code that does it for you (in the parsing function).
 Advanced converters
 -------------------
 
-Remeber those format units you skipped for your first
+Remember those format units you skipped for your first
 time because they were advanced?  Here's how to handle those too.
 
 The trick is, all those format units take arguments--either
@@ -1020,12 +1020,12 @@ any of the default arguments you can omit the parentheses.
 the ``"as"`` should come before the return converter.)
 
 There's one additional complication when using return converters: how do you
-indicate an error has occured?  Normally, a function returns a valid (non-``NULL``)
+indicate an error has occurred?  Normally, a function returns a valid (non-``NULL``)
 pointer for success, and ``NULL`` for failure.  But if you use an integer return converter,
 all integers are valid.  How can Argument Clinic detect an error?  Its solution: each return
 converter implicitly looks for a special value that indicates an error.  If you return
 that value, and an error has been set (``PyErr_Occurred()`` returns a true
-value), then the generated code will propogate the error.  Otherwise it will
+value), then the generated code will propagate the error.  Otherwise it will
 encode the value you return like normal.
 
 Currently Argument Clinic supports only a few return converters::
@@ -1573,7 +1573,7 @@ The fourth new directive is ``set``::
 ``line_prefix`` is a string that will be prepended to every line of Clinic's output;
 ``line_suffix`` is a string that will be appended to every line of Clinic's output.
 
-Both of these suport two format strings:
+Both of these support two format strings:
 
   ``{block comment start}``
     Turns into the string ``/*``, the start-comment text sequence for C files.

Doc/howto/pyporting.rst

@@ -60,7 +60,7 @@ If your project is on the Cheeseshop_/PyPI_, make sure it has the proper
 `trove classifiers`_ to signify what versions of Python it **currently**
 supports. At minimum you should specify the major version(s), e.g.
 ``Programming Language :: Python :: 2`` if your project currently only supports
-Python 2. It is preferrable that you be as specific as possible by listing every
+Python 2. It is preferable that you be as specific as possible by listing every
 major/minor version of Python that you support, e.g. if your project supports
 Python 2.6 and 2.7, then you want the classifiers of::
 

Doc/howto/regex.rst

@@ -852,7 +852,7 @@ keep track of the group numbers.  There are two features which help with this
 problem.  Both of them use a common syntax for regular expression extensions, so
 we'll look at that first.
 
-Perl 5 is well-known for its powerful additions to standard regular expressions.
+Perl 5 is well known for its powerful additions to standard regular expressions.
 For these new features the Perl developers couldn't choose new single-keystroke metacharacters
 or new special sequences beginning with ``\`` without making Perl's regular
 expressions confusingly different from standard REs.  If they chose ``&`` as a

Doc/howto/sockets.rst

@@ -234,7 +234,7 @@ messages to be sent back to back (without some kind of reply), and you pass
 following message. You'll need to put that aside and hold onto it, until it's
 needed.
 
-Prefixing the message with it's length (say, as 5 numeric characters) gets more
+Prefixing the message with its length (say, as 5 numeric characters) gets more
 complex, because (believe it or not), you may not get all 5 characters in one
 ``recv``. In playing around, you'll get away with it; but in high network loads,
 your code will very quickly break unless you use two ``recv`` loops - the first

Doc/library/argparse.rst

@@ -1873,7 +1873,7 @@ Customizing file parsing
 
    Arguments that are read from a file (see the *fromfile_prefix_chars*
    keyword argument to the :class:`ArgumentParser` constructor) are read one
-   argument per line. :meth:`convert_arg_line_to_args` can be overriden for
+   argument per line. :meth:`convert_arg_line_to_args` can be overridden for
    fancier reading.
 
    This method takes a single argument *arg_line* which is a string read from

Doc/library/asynchat.rst

@@ -147,40 +147,6 @@ connection requests.
    by the channel after :meth:`found_terminator` is called.
 
 
-asynchat - Auxiliary Classes
-------------------------------------------
-
-.. class:: fifo(list=None)
-
-   A :class:`fifo` holding data which has been pushed by the application but
-   not yet popped for writing to the channel.  A :class:`fifo` is a list used
-   to hold data and/or producers until they are required.  If the *list*
-   argument is provided then it should contain producers or data items to be
-   written to the channel.
-
-
-   .. method:: is_empty()
-
-      Returns ``True`` if and only if the fifo is empty.
-
-
-   .. method:: first()
-
-      Returns the least-recently :meth:`push`\ ed item from the fifo.
-
-
-   .. method:: push(data)
-
-      Adds the given data (which may be a string or a producer object) to the
-      producer fifo.
-
-
-   .. method:: pop()
-
-      If the fifo is not empty, returns ``True, first()``, deleting the popped
-      item.  Returns ``False, None`` for an empty fifo.
-
-
 .. _asynchat-example:
 
 asynchat Example

Doc/library/cmd.rst

@@ -252,7 +252,7 @@ immediate playback::
             'Move turtle to an absolute position with changing orientation.  GOTO 100 200'
             goto(*parse(arg))
         def do_home(self, arg):
-            'Return turtle to the home postion:  HOME'
+            'Return turtle to the home position:  HOME'
             home()
         def do_circle(self, arg):
             'Draw circle with given radius an options extent and steps:  CIRCLE 50'

Doc/library/code.rst

@@ -4,6 +4,7 @@
 .. module:: code
    :synopsis: Facilities to implement read-eval-print loops.
 
+**Source code:** :source:`Lib/code.py`
 
 The ``code`` module provides facilities to implement read-eval-print loops in
 Python.  Two classes and convenience functions are included which can be used to
@@ -165,4 +166,3 @@ interpreter objects as well as the following additions.
    newline.  When the user enters the EOF key sequence, :exc:`EOFError` is raised.
    The base implementation reads from ``sys.stdin``; a subclass may replace this
    with a different implementation.
-

Doc/library/codecs.rst

@@ -7,6 +7,7 @@
 .. sectionauthor:: Marc-André Lemburg <[email protected]>
 .. sectionauthor:: Martin v. Löwis <[email protected]>
 
+**Source code:** :source:`Lib/codecs.py`
 
 .. index::
    single: Unicode
@@ -22,21 +23,19 @@ manages the codec and error handling lookup process.
 
 It defines the following functions:
 
-.. function:: encode(obj, [encoding[, errors]])
+.. function:: encode(obj, encoding='utf-8', errors='strict')
 
-   Encodes *obj* using the codec registered for *encoding*. The default
-   encoding is ``utf-8``.
+   Encodes *obj* using the codec registered for *encoding*.
 
    *Errors* may be given to set the desired error handling scheme. The
    default error handler is ``strict`` meaning that encoding errors raise
    :exc:`ValueError` (or a more codec specific subclass, such as
    :exc:`UnicodeEncodeError`). Refer to :ref:`codec-base-classes` for more
    information on codec error handling.
 
-.. function:: decode(obj, [encoding[, errors]])
+.. function:: decode(obj, encoding='utf-8', errors='strict')
 
-   Decodes *obj* using the codec registered for *encoding*. The default
-   encoding is ``utf-8``.
+   Decodes *obj* using the codec registered for *encoding*.
 
    *Errors* may be given to set the desired error handling scheme. The
    default error handler is ``strict`` meaning that decoding errors raise
@@ -1420,4 +1419,3 @@ This module implements a variant of the UTF-8 codec: On encoding a UTF-8 encoded
 BOM will be prepended to the UTF-8 encoded bytes. For the stateful encoder this
 is only done once (on the first write to the byte stream).  For decoding an
 optional UTF-8 encoded BOM at the start of the data will be skipped.
-

Doc/library/collections.abc.rst

@@ -179,7 +179,7 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
 (3)
    The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value
    for the set; however, :meth:`__hash__` is not defined because not all sets
-   are hashable or immutable.  To add set hashabilty using mixins,
+   are hashable or immutable.  To add set hashability using mixins,
    inherit from both :meth:`Set` and :meth:`Hashable`, then define
    ``__hash__ = Set._hash``.