#23144: merge with 3.4.

16 files changed, 771 insertions, 269 deletions

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 3c0f4b98cd..ed62deaec1 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -152,7 +152,7 @@ Unless otherwise stated, buffers are not NUL-terminated.
    any conversion.  Raises :exc:`TypeError` if the object is not a Unicode
    object.  The C variable may also be declared as :c:type:`PyObject\*`.
 
-``w*`` (:class:`bytearray` or read-write byte-oriented buffer) [Py_buffer]
+``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
    This format accepts any object which implements the read-write buffer
    interface. It fills a :c:type:`Py_buffer` structure provided by the caller.
    The buffer may contain embedded null bytes. The caller have to call
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index d099ace9ef..46c19d3ca3 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -96,8 +96,8 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
       block of the exporter. For example, with negative :c:member:`~Py_buffer.strides`
       the value may point to the end of the memory block.
 
-      For contiguous arrays, the value points to the beginning of the memory
-      block.
+      For :term:`contiguous` arrays, the value points to the beginning of
+      the memory block.
 
    .. c:member:: void \*obj
 
@@ -281,11 +281,14 @@ of the flags below it.
 +-----------------------------+-------+---------+------------+
 
 
+.. index:: contiguous, C-contiguous, Fortran contiguous
+
 contiguity requests
 ~~~~~~~~~~~~~~~~~~~
 
-C or Fortran contiguity can be explicitly requested, with and without stride
-information. Without stride information, the buffer must be C-contiguous.
+C or Fortran :term:`contiguity <contiguous>` can be explicitly requested,
+with and without stride information. Without stride information, the buffer
+must be C-contiguous.
 
 .. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|
 
@@ -466,13 +469,13 @@ Buffer-related functions
 .. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
 
    Return 1 if the memory defined by the *view* is C-style (*order* is
-   ``'C'``) or Fortran-style (*order* is ``'F'``) contiguous or either one
+   ``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one
    (*order* is ``'A'``).  Return 0 otherwise.
 
 
 .. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char order)
 
-   Fill the *strides* array with byte-strides of a contiguous (C-style if
+   Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style if
    *order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the
    given shape with the given number of bytes per element.
 
diff --git a/Doc/c-api/codec.rst b/Doc/c-api/codec.rst
index 83252afbb7..dfe3d436e5 100644
--- a/Doc/c-api/codec.rst
+++ b/Doc/c-api/codec.rst
@@ -116,3 +116,8 @@ Registry API for Unicode encoding error handlers
    Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and
    ``\U``).
 
+.. c:function:: PyObject* PyCodec_NameReplaceErrors(PyObject *exc)
+
+   Replace the unicode encode error with ``\N{...}`` escapes.
+
+   .. versionadded:: 3.5
diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst
index 2d5638670e..47dab81891 100644
--- a/Doc/c-api/concrete.rst
+++ b/Doc/c-api/concrete.rst
@@ -112,5 +112,6 @@ Other Objects
    weakref.rst
    capsule.rst
    gen.rst
+   coro.rst
    datetime.rst
 
diff --git a/Doc/c-api/coro.rst b/Doc/c-api/coro.rst
new file mode 100644
index 0000000000..2fe50b5d8c
--- /dev/null
+++ b/Doc/c-api/coro.rst
@@ -0,0 +1,34 @@
+.. highlightlang:: c
+
+.. _coro-objects:
+
+Coroutine Objects
+-----------------
+
+.. versionadded:: 3.5
+
+Coroutine objects are what functions declared with an ``async`` keyword
+return.
+
+
+.. c:type:: PyCoroObject
+
+   The C structure used for coroutine objects.
+
+
+.. c:var:: PyTypeObject PyCoro_Type
+
+   The type object corresponding to coroutine objects.
+
+
+.. c:function:: int PyCoro_CheckExact(PyObject *ob)
+
+   Return true if *ob*'s type is *PyCoro_Type*; *ob* must not be *NULL*.
+
+
+.. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)
+
+   Create and return a new coroutine object based on the *frame* object,
+   with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
+   A reference to *frame* is stolen by this function.  The *frame* argument
+   must not be *NULL*.
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index c2df767998..3fd69ba80f 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -9,13 +9,19 @@ Exception Handling
 
 The functions described in this chapter will let you handle and raise Python
 exceptions.  It is important to understand some of the basics of Python
-exception handling.  It works somewhat like the Unix :c:data:`errno` variable:
+exception handling.  It works somewhat like the POSIX :c:data:`errno` variable:
 there is a global indicator (per thread) of the last error that occurred.  Most
-functions don't clear this on success, but will set it to indicate the cause of
-the error on failure.  Most functions also return an error indicator, usually
-*NULL* if they are supposed to return a pointer, or ``-1`` if they return an
-integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and
-``0`` for failure).
+C API functions don't clear this on success, but will set it to indicate the
+cause of the error on failure.  Most C API functions also return an error
+indicator, usually *NULL* if they are supposed to return a pointer, or ``-1``
+if they return an integer (exception: the :c:func:`PyArg_\*` functions
+return ``1`` for success and ``0`` for failure).
+
+Concretely, the error indicator consists of three object pointers: the
+exception's type, the exception's value, and the traceback object.  Any
+of those pointers can be NULL if non-set (although some combinations are
+forbidden, for example you can't have a non-NULL traceback if the exception
+type is NULL).
 
 When a function must fail because some function it called failed, it generally
 doesn't set the error indicator; the function it called already set it.  It is
@@ -27,12 +33,21 @@ the caller that an error has been set.  If the error is not handled or carefully
 propagated, additional calls into the Python/C API may not behave as intended
 and may fail in mysterious ways.
 
-The error indicator consists of three Python objects corresponding to the result
-of ``sys.exc_info()``.  API functions exist to interact with the error indicator
-in various ways.  There is a separate error indicator for each thread.
+.. note::
+   The error indicator is **not** the result of :func:`sys.exc_info()`.
+   The former corresponds to an exception that is not yet caught (and is
+   therefore still propagating), while the latter returns an exception after
+   it is caught (and has therefore stopped propagating).
 
-.. XXX Order of these should be more thoughtful.
-   Either alphabetical or some kind of structure.
+
+Printing and clearing
+=====================
+
+
+.. c:function:: void PyErr_Clear()
+
+   Clear the error indicator.  If the error indicator is not set, there is no
+   effect.
 
 
 .. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
@@ -51,127 +66,24 @@ in various ways.  There is a separate error indicator for each thread.
    Alias for ``PyErr_PrintEx(1)``.
 
 
-.. c:function:: PyObject* PyErr_Occurred()
-
-   Test whether the error indicator is set.  If set, return the exception *type*
-   (the first argument to the last call to one of the :c:func:`PyErr_Set\*`
-   functions or to :c:func:`PyErr_Restore`).  If not set, return *NULL*.  You do not
-   own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
-   it.
-
-   .. note::
-
-      Do not compare the return value to a specific exception; use
-      :c:func:`PyErr_ExceptionMatches` instead, shown below.  (The comparison could
-      easily fail since the exception may be an instance instead of a class, in the
-      case of a class exception, or it may be a subclass of the expected exception.)
-
-
-.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
-
-   Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``.  This
-   should only be called when an exception is actually set; a memory access
-   violation will occur if no exception has been raised.
-
-
-.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
-
-   Return true if the *given* exception matches the exception in *exc*.  If
-   *exc* is a class object, this also returns true when *given* is an instance
-   of a subclass.  If *exc* is a tuple, all exceptions in the tuple (and
-   recursively in subtuples) are searched for a match.
-
-
-.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
-
-   Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
-   can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
-   not an instance of the  same class.  This function can be used to instantiate
-   the class in that case.  If the values are already normalized, nothing happens.
-   The delayed normalization is implemented to improve performance.
-
-   .. note::
-
-      This function *does not* implicitly set the ``__traceback__``
-      attribute on the exception value. If setting the traceback
-      appropriately is desired, the following additional snippet is needed::
-
-         if (tb != NULL) {
-           PyException_SetTraceback(val, tb);
-         }
-
-
-.. c:function:: void PyErr_Clear()
-
-   Clear the error indicator.  If the error indicator is not set, there is no
-   effect.
-
-
-.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
-
-   Retrieve the error indicator into three variables whose addresses are passed.
-   If the error indicator is not set, set all three variables to *NULL*.  If it is
-   set, it will be cleared and you own a reference to each object retrieved.  The
-   value and traceback object may be *NULL* even when the type object is not.
-
-   .. note::
-
-      This function is normally only used by code that needs to handle exceptions or
-      by code that needs to save and restore the error indicator temporarily.
-
-
-.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
-
-   Set  the error indicator from the three objects.  If the error indicator is
-   already set, it is cleared first.  If the objects are *NULL*, the error
-   indicator is cleared.  Do not pass a *NULL* type and non-*NULL* value or
-   traceback.  The exception type should be a class.  Do not pass an invalid
-   exception type or value. (Violating these rules will cause subtle problems
-   later.)  This call takes away a reference to each object: you must own a
-   reference to each object before the call and after the call you no longer own
-   these references.  (If you don't understand this, don't use this function.  I
-   warned you.)
-
-   .. note::
-
-      This function is normally only used by code that needs to save and restore the
-      error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current
-      exception state.
-
-
-.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
-
-   Retrieve the exception info, as known from ``sys.exc_info()``.  This refers
-   to an exception that was already caught, not to an exception that was
-   freshly raised.  Returns new references for the three objects, any of which
-   may be *NULL*.  Does not modify the exception info state.
-
-   .. note::
-
-      This function is not normally used by code that wants to handle exceptions.
-      Rather, it can be used when code needs to save and restore the exception
-      state temporarily.  Use :c:func:`PyErr_SetExcInfo` to restore or clear the
-      exception state.
-
-   .. versionadded:: 3.3
-
+.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
 
-.. c:function:: void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
+   This utility function prints a warning message to ``sys.stderr`` when an
+   exception has been set but it is impossible for the interpreter to actually
+   raise the exception.  It is used, for example, when an exception occurs in an
+   :meth:`__del__` method.
 
-   Set the exception info, as known from ``sys.exc_info()``.  This refers
-   to an exception that was already caught, not to an exception that was
-   freshly raised.  This function steals the references of the arguments.
-   To clear the exception state, pass *NULL* for all three arguments.
-   For general rules about the three arguments, see :c:func:`PyErr_Restore`.
+   The function is called with a single argument *obj* that identifies the context
+   in which the unraisable exception occurred. The repr of *obj* will be printed in
+   the warning message.
 
-   .. note::
 
-      This function is not normally used by code that wants to handle exceptions.
-      Rather, it can be used when code needs to save and restore the exception
-      state temporarily.  Use :c:func:`PyErr_GetExcInfo` to read the exception
-      state.
+Raising exceptions
+==================
 
-   .. versionadded:: 3.3
+These functions help you set the current thread's error indicator.
+For convenience, some of these functions will always return a
+NULL pointer for use in a ``return`` statement.
 
 
 .. c:function:: void PyErr_SetString(PyObject *type, const char *message)
@@ -197,6 +109,14 @@ in various ways.  There is a separate error indicator for each thread.
    string.
 
 
+.. c:function:: PyObject* PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)
+
+   Same as :c:func:`PyErr_Format`, but taking a :c:type:`va_list` argument rather
+   than a variable number of arguments.
+
+   .. versionadded:: 3.5
+
+
 .. c:function:: void PyErr_SetNone(PyObject *type)
 
    This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
@@ -346,6 +266,22 @@ in various ways.  There is a separate error indicator for each thread.
    use.
 
 
+Issuing warnings
+================
+
+Use these functions to issue warnings from C code.  They mirror similar
+functions exported by the Python :mod:`warnings` module.  They normally
+print a warning message to *sys.stderr*; however, it is
+also possible that the user has specified that warnings are to be turned into
+errors, and in that case they will raise an exception.  It is also possible that
+the functions raise an exception because of a problem with the warning machinery.
+The return value is ``0`` if no exception is raised, or ``-1`` if an exception
+is raised.  (It is not possible to determine whether a warning message is
+actually printed, nor what the reason is for the exception; this is
+intentional.)  If an exception is raised, the caller should do its normal
+exception handling (for example, :c:func:`Py_DECREF` owned references and return
+an error value).
+
 .. c:function:: int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)
 
    Issue a warning message.  The *category* argument is a warning category (see
@@ -355,18 +291,6 @@ in various ways.  There is a separate error indicator for each thread.
    is the function calling :c:func:`PyErr_WarnEx`, 2 is  the function above that,
    and so forth.
 
-   This function normally prints a warning message to *sys.stderr*; however, it is
-   also possible that the user has specified that warnings are to be turned into
-   errors, and in that case this will raise an exception.  It is also possible that
-   the function raises an exception because of a problem with the warning machinery
-   (the implementation imports the :mod:`warnings` module to do the heavy lifting).
-   The return value is ``0`` if no exception is raised, or ``-1`` if an exception
-   is raised.  (It is not possible to determine whether a warning message is
-   actually printed, nor what the reason is for the exception; this is
-   intentional.)  If an exception is raised, the caller should do its normal
-   exception handling (for example, :c:func:`Py_DECREF` owned references and return
-   an error value).
-
    Warning categories must be subclasses of :c:data:`Warning`; the default warning
    category is :c:data:`RuntimeWarning`.  The standard Python warning categories are
    available as global variables whose names are ``PyExc_`` followed by the Python
@@ -410,6 +334,139 @@ in various ways.  There is a separate error indicator for each thread.
    .. versionadded:: 3.2
 
 
+Querying the error indicator
+============================
+
+.. c:function:: PyObject* PyErr_Occurred()
+
+   Test whether the error indicator is set.  If set, return the exception *type*
+   (the first argument to the last call to one of the :c:func:`PyErr_Set\*`
+   functions or to :c:func:`PyErr_Restore`).  If not set, return *NULL*.  You do not
+   own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
+   it.
+
+   .. note::
+
+      Do not compare the return value to a specific exception; use
+      :c:func:`PyErr_ExceptionMatches` instead, shown below.  (The comparison could
+      easily fail since the exception may be an instance instead of a class, in the
+      case of a class exception, or it may be a subclass of the expected exception.)
+
+
+.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
+
+   Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``.  This
+   should only be called when an exception is actually set; a memory access
+   violation will occur if no exception has been raised.
+
+
+.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
+
+   Return true if the *given* exception matches the exception type in *exc*.  If
+   *exc* is a class object, this also returns true when *given* is an instance
+   of a subclass.  If *exc* is a tuple, all exception types in the tuple (and
+   recursively in subtuples) are searched for a match.
+
+
+.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
+
+   Retrieve the error indicator into three variables whose addresses are passed.
+   If the error indicator is not set, set all three variables to *NULL*.  If it is
+   set, it will be cleared and you own a reference to each object retrieved.  The
+   value and traceback object may be *NULL* even when the type object is not.
+
+   .. note::
+
+      This function is normally only used by code that needs to catch exceptions or
+      by code that needs to save and restore the error indicator temporarily, e.g.::
+
+         {
+            PyObject **type, **value, **traceback;
+            PyErr_Fetch(&type, &value, &traceback);
+
+            /* ... code that might produce other errors ... */
+
+            PyErr_Restore(type, value, traceback);
+         }
+
+
+.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
+
+   Set  the error indicator from the three objects.  If the error indicator is
+   already set, it is cleared first.  If the objects are *NULL*, the error
+   indicator is cleared.  Do not pass a *NULL* type and non-*NULL* value or
+   traceback.  The exception type should be a class.  Do not pass an invalid
+   exception type or value. (Violating these rules will cause subtle problems
+   later.)  This call takes away a reference to each object: you must own a
+   reference to each object before the call and after the call you no longer own
+   these references.  (If you don't understand this, don't use this function.  I
+   warned you.)
+
+   .. note::
+
+      This function is normally only used by code that needs to save and restore the
+      error indicator temporarily.  Use :c:func:`PyErr_Fetch` to save the current
+      error indicator.
+
+
+.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
+
+   Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
+   can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
+   not an instance of the  same class.  This function can be used to instantiate
+   the class in that case.  If the values are already normalized, nothing happens.
+   The delayed normalization is implemented to improve performance.
+
+   .. note::
+
+      This function *does not* implicitly set the ``__traceback__``
+      attribute on the exception value. If setting the traceback
+      appropriately is desired, the following additional snippet is needed::
+
+         if (tb != NULL) {
+           PyException_SetTraceback(val, tb);
+         }
+
+
+.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
+
+   Retrieve the exception info, as known from ``sys.exc_info()``.  This refers
+   to an exception that was *already caught*, not to an exception that was
+   freshly raised.  Returns new references for the three objects, any of which
+   may be *NULL*.  Does not modify the exception info state.
+
+   .. note::
+
+      This function is not normally used by code that wants to handle exceptions.
+      Rather, it can be used when code needs to save and restore the exception
+      state temporarily.  Use :c:func:`PyErr_SetExcInfo` to restore or clear the
+      exception state.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
+
+   Set the exception info, as known from ``sys.exc_info()``.  This refers
+   to an exception that was *already caught*, not to an exception that was
+   freshly raised.  This function steals the references of the arguments.
+   To clear the exception state, pass *NULL* for all three arguments.
+   For general rules about the three arguments, see :c:func:`PyErr_Restore`.
+
+   .. note::
+
+      This function is not normally used by code that wants to handle exceptions.
+      Rather, it can be used when code needs to save and restore the exception
+      state temporarily.  Use :c:func:`PyErr_GetExcInfo` to read the exception
+      state.
+
+   .. versionadded:: 3.3
+
+
+Signal Handling
+===============
+
+
 .. c:function:: int PyErr_CheckSignals()
 
    .. index::
@@ -443,13 +500,21 @@ in various ways.  There is a separate error indicator for each thread.
 
 .. c:function:: int PySignal_SetWakeupFd(int fd)
 
-   This utility function specifies a file descriptor to which a ``'\0'`` byte will
-   be written whenever a signal is received.  It returns the previous such file
-   descriptor.  The value ``-1`` disables the feature; this is the initial state.
+   This utility function specifies a file descriptor to which the signal number
+   is written as a single byte whenever a signal is received. *fd* must be
+   non-blocking. It returns the previous such file descriptor.
+
+   The value ``-1`` disables the feature; this is the initial state.
    This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
    error checking.  *fd* should be a valid file descriptor.  The function should
    only be called from the main thread.
 
+   .. versionchanged:: 3.5
+      On Windows, the function now also supports socket handles.
+
+
+Exception Classes
+=================
 
 .. c:function:: PyObject* PyErr_NewException(const char *name, PyObject *base, PyObject *dict)
 
@@ -475,18 +540,6 @@ in various ways.  There is a separate error indicator for each thread.
    .. versionadded:: 3.2
 
 
-.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
-
-   This utility function prints a warning message to ``sys.stderr`` when an
-   exception has been set but it is impossible for the interpreter to actually
-   raise the exception.  It is used, for example, when an exception occurs in an
-   :meth:`__del__` method.
-
-   The function is called with a single argument *obj* that identifies the context
-   in which the unraisable exception occurred. The repr of *obj* will be printed in
-   the warning message.
-
-
 Exception Objects
 =================
 
@@ -630,12 +683,12 @@ recursion depth automatically).
    sets a :exc:`MemoryError` and returns a nonzero value.
 
    The function then checks if the recursion limit is reached.  If this is the
-   case, a :exc:`RuntimeError` is set and a nonzero value is returned.
+   case, a :exc:`RecursionError` is set and a nonzero value is returned.
    Otherwise, zero is returned.
 
    *where* should be a string such as ``" in instance check"`` to be
-   concatenated to the :exc:`RuntimeError` message caused by the recursion depth
-   limit.
+   concatenated to the :exc:`RecursionError` message caused by the recursion
+   depth limit.
 
 .. c:function:: void Py_LeaveRecursiveCall()
 
@@ -747,6 +800,8 @@ the variables:
 +-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ProcessLookupError`      | :exc:`ProcessLookupError`       |          |
 +-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_RecursionError`          | :exc:`RecursionError`           |          |
++-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ReferenceError`          | :exc:`ReferenceError`           | \(2)     |
 +-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_RuntimeError`            | :exc:`RuntimeError`             |          |
@@ -776,6 +831,9 @@ the variables:
    :c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError`
    and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`.
 
+.. versionadded:: 3.5
+   :c:data:`PyExc_RecursionError`.
+
 
 These are compatibility aliases to :c:data:`PyExc_OSError`:
 
@@ -824,6 +882,7 @@ These are compatibility aliases to :c:data:`PyExc_OSError`:
    single: PyExc_OverflowError
    single: PyExc_PermissionError
    single: PyExc_ProcessLookupError
+   single: PyExc_RecursionError
    single: PyExc_ReferenceError
    single: PyExc_RuntimeError
    single: PyExc_SyntaxError
diff --git a/Doc/c-api/gen.rst b/Doc/c-api/gen.rst
index 33cd27a5aa..3ab073b191 100644
--- a/Doc/c-api/gen.rst
+++ b/Doc/c-api/gen.rst
@@ -7,7 +7,7 @@ Generator Objects
 
 Generator objects are what Python uses to implement generator iterators. They
 are normally created by iterating over a function that yields values, rather
-than explicitly calling :c:func:`PyGen_New`.
+than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
 
 
 .. c:type:: PyGenObject
@@ -20,19 +20,25 @@ than explicitly calling :c:func:`PyGen_New`.
    The type object corresponding to generator objects
 
 
-.. c:function:: int PyGen_Check(ob)
+.. c:function:: int PyGen_Check(PyObject *ob)
 
    Return true if *ob* is a generator object; *ob* must not be *NULL*.
 
 
-.. c:function:: int PyGen_CheckExact(ob)
+.. c:function:: int PyGen_CheckExact(PyObject *ob)
 
-   Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
-   be *NULL*.
+   Return true if *ob*'s type is *PyGen_Type*; *ob* must not be *NULL*.
 
 
 .. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
 
-   Create and return a new generator object based on the *frame* object. A
-   reference to *frame* is stolen by this function. The parameter must not be
+   Create and return a new generator object based on the *frame* object.
+   A reference to *frame* is stolen by this function. The argument must not be
    *NULL*.
+
+.. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
+
+   Create and return a new generator object based on the *frame* object,
+   with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
+   A reference to *frame* is stolen by this function.  The *frame* argument
+   must not be *NULL*.
diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
index 60865f456f..bf1b49577e 100644
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -183,9 +183,9 @@ Importing Modules
 
 .. c:function:: long PyImport_GetMagicNumber()
 
-   Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
-   :file:`.pyo` files).  The magic number should be present in the first four bytes
-   of the bytecode file, in little-endian byte order. Returns -1 on error.
+   Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` file).
+   The magic number should be present in the first four bytes of the bytecode
+   file, in little-endian byte order. Returns -1 on error.
 
    .. versionchanged:: 3.3
       Return value of -1 upon failure.
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 4bb50649ef..81823bf383 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -134,6 +134,9 @@ Process-wide parameters
    change for the duration of the program's execution.  No code in the Python
    interpreter will change the contents of this storage.
 
+   Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+   :c:type:`wchar_*` string.
+
 
 .. c:function:: wchar* Py_GetProgramName()
 
@@ -245,6 +248,9 @@ Process-wide parameters
    :data:`sys.exec_prefix` to be empty.  It is up to the caller to modify these
    if required after calling :c:func:`Py_Initialize`.
 
+   Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+   :c:type:`wchar_*` string.
+
    The path argument is copied internally, so the caller may free it after the
    call completes.
 
@@ -344,6 +350,9 @@ Process-wide parameters
      :data:`sys.path`, which is the same as prepending the current working
      directory (``"."``).
 
+   Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+   :c:type:`wchar_*` string.
+
    .. note::
       It is recommended that applications embedding the Python interpreter
       for purposes other than executing a single script pass 0 as *updatepath*,
@@ -368,6 +377,9 @@ Process-wide parameters
    to 1 unless the :program:`python` interpreter was started with the
    :option:`-I`.
 
+   Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+   :c:type:`wchar_*` string.
+
    .. versionchanged:: 3.4 The *updatepath* value depends on :option:`-I`.
 
 
@@ -382,6 +394,9 @@ Process-wide parameters
    execution.  No code in the Python interpreter will change the contents of
    this storage.
 
+   Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+   :c:type:`wchar_*` string.
+
 
 .. c:function:: w_char* Py_GetPythonHome()
 
@@ -858,6 +873,8 @@ been created.
       instead.
 
 
+.. _sub-interpreter-support:
+
 Sub-interpreter support
 =======================
 
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 7908622d2b..7339006b5e 100644
--- a/Doc/c-api/memory.rst
+++ b/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.
 
diff --git a/Doc/c-api/memoryview.rst b/Doc/c-api/memoryview.rst
index 5e50977cbe..9f6bfd751a 100644
--- a/Doc/c-api/memoryview.rst
+++ b/Doc/c-api/memoryview.rst
@@ -35,7 +35,7 @@ any other object.
 
 .. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
 
-   Create a memoryview object to a contiguous chunk of memory (in either
+   Create a memoryview object to a :term:`contiguous` chunk of memory (in either
    'C' or 'F'ortran *order*) from an object that defines the buffer
    interface. If memory is contiguous, the memoryview object points to the
    original memory. Otherwise, a copy is made and the memoryview points to a
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index 985a347d63..ef778ccaed 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -7,8 +7,6 @@ Module Objects
 
 .. index:: object: module
 
-There are only a few functions special to module objects.
-
 
 .. c:var:: PyTypeObject PyModule_Type
 
@@ -84,6 +82,18 @@ There are only a few functions special to module objects.
    Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
    ``'utf-8'``.
 
+.. c:function:: void* PyModule_GetState(PyObject *module)
+
+   Return the "state" of the module, that is, a pointer to the block of memory
+   allocated at module creation time, or *NULL*.  See
+   :c:member:`PyModuleDef.m_size`.
+
+
+.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
+
+   Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
+   created, or *NULL* if the module wasn't created from a definition.
+
 
 .. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
 
@@ -109,55 +119,109 @@ There are only a few functions special to module objects.
       unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
 
 
-.. c:function:: void* PyModule_GetState(PyObject *module)
+.. _initializing-modules:
 
-   Return the "state" of the module, that is, a pointer to the block of memory
-   allocated at module creation time, or *NULL*.  See
-   :c:member:`PyModuleDef.m_size`.
+Initializing C modules
+^^^^^^^^^^^^^^^^^^^^^^
 
+Modules objects are usually created from extension modules (shared libraries
+which export an initialization function), or compiled-in modules
+(where the initialization function is added using :c:func:`PyImport_AppendInittab`).
+See :ref:`building` or :ref:`extending-with-embedding` for details.
 
-.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
+The initialization function can either pass pass a module definition instance
+to :c:func:`PyModule_Create`, and return the resulting module object,
+or request "multi-phase initialization" by returning the definition struct itself.
 
-   Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
-   created, or *NULL* if the module wasn't created with
-   :c:func:`PyModule_Create`.
+.. c:type:: PyModuleDef
 
-.. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
+   The module definition struct, which holds all information needed to create
+   a module object. There is usually only one statically initialized variable
+   of this type for each module.
 
-   Returns the module object that was created from *def* for the current interpreter.
-   This method requires that the module object has been attached to the interpreter state with
-   :c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
-   found or has not been attached to the interpreter state yet, it returns NULL.
+   .. c:member:: PyModuleDef_Base m_base
 
-.. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def)
+      Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
 
-   Attaches the module object passed to the function to the interpreter state. This allows
-   the module object to be accessible via
-   :c:func:`PyState_FindModule`.
+   .. c:member:: char* m_name
 
-   .. versionadded:: 3.3
+      Name for the new module.
 
-.. c:function:: int PyState_RemoveModule(PyModuleDef *def)
+   .. c:member:: char* m_doc
 
-   Removes the module object created from *def* from the interpreter state.
+      Docstring for the module; usually a docstring variable created with
+      :c:func:`PyDoc_STRVAR` is used.
 
-   .. versionadded:: 3.3
+   .. c:member:: Py_ssize_t m_size
 
-Initializing C modules
-^^^^^^^^^^^^^^^^^^^^^^
+      Module state may be kept in a per-module memory area that can be
+      retrieved with :c:func:`PyModule_GetState`, rather than in static globals.
+      This makes modules safe for use in multiple sub-interpreters.
+
+      This memory area is allocated based on *m_size* on module creation,
+      and freed when the module object is deallocated, after the
+      :c:member:`m_free` function has been called, if present.
+
+      Setting ``m_size`` to ``-1`` means that the module does not support
+      sub-interpreters, because it has global state.
 
-These functions are usually used in the module initialization function.
+      Setting it to a non-negative value means that the module can be
+      re-initialized and specifies the additional amount of memory it requires
+      for its state. Non-negative ``m_size`` is required for multi-phase
+      initialization.
 
-.. c:function:: PyObject* PyModule_Create(PyModuleDef *module)
+      See :PEP:`3121` for more details.
+
+   .. c:member:: PyMethodDef* m_methods
 
-   Create a new module object, given the definition in *module*.  This behaves
+      A pointer to a table of module-level functions, described by
+      :c:type:`PyMethodDef` values.  Can be *NULL* if no functions are present.
+
+   .. c:member:: PyModuleDef_Slot* m_slots
+
+      An array of slot definitions for multi-phase initialization, terminated by
+      a ``{0, NULL}`` entry.
+      When using single-phase initialization, *m_slots* must be *NULL*.
+
+      .. versionchanged:: 3.5
+
+         Prior to version 3.5, this member was always set to *NULL*,
+         and was defined as:
+
+           .. c:member:: inquiry m_reload
+
+   .. c:member:: traverseproc m_traverse
+
+      A traversal function to call during GC traversal of the module object, or
+      *NULL* if not needed.
+
+   .. c:member:: inquiry m_clear
+
+      A clear function to call during GC clearing of the module object, or
+      *NULL* if not needed.
+
+   .. c:member:: freefunc m_free
+
+      A function to call during deallocation of the module object, or *NULL* if
+      not needed.
+
+Single-phase initialization
+...........................
+
+The module initialization function may create and return the module object
+directly. This is referred to as "single-phase initialization", and uses one
+of the following two module creation functions:
+
+.. c:function:: PyObject* PyModule_Create(PyModuleDef *def)
+
+   Create a new module object, given the definition in *def*.  This behaves
    like :c:func:`PyModule_Create2` with *module_api_version* set to
    :const:`PYTHON_API_VERSION`.
 
 
-.. c:function:: PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)
+.. c:function:: PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)
 
-   Create a new module object, given the definition in *module*, assuming the
+   Create a new module object, given the definition in *def*, assuming the
    API version *module_api_version*.  If that version does not match the version
    of the running interpreter, a :exc:`RuntimeWarning` is emitted.
 
@@ -166,69 +230,179 @@ These functions are usually used in the module initialization function.
       Most uses of this function should be using :c:func:`PyModule_Create`
       instead; only use this if you are sure you need it.
 
+Before it is returned from in the initialization function, the resulting module
+object is typically populated using functions like :c:func:`PyModule_AddObject`.
 
-.. c:type:: PyModuleDef
+.. _multi-phase-initialization:
 
-   This struct holds all information that is needed to create a module object.
-   There is usually only one static variable of that type for each module, which
-   is statically initialized and then passed to :c:func:`PyModule_Create` in the
-   module initialization function.
+Multi-phase initialization
+..........................
 
-   .. c:member:: PyModuleDef_Base m_base
+An alternate way to specify extensions is to request "multi-phase initialization".
+Extension modules created this way behave more like Python modules: the
+initialization is split between the *creation phase*, when the module object
+is created, and the *execution phase*, when it is populated.
+The distinction is similar to the :py:meth:`__new__` and :py:meth:`__init__` methods
+of classes.
 
-      Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
+Unlike modules created using single-phase initialization, these modules are not
+singletons: if the *sys.modules* entry is removed and the module is re-imported,
+a new module object is created, and the old module is subject to normal garbage
+collection -- as with Python modules.
+By default, multiple modules created from the same definition should be
+independent: changes to one should not affect the others.
+This means that all state should be specific to the module object (using e.g.
+using :c:func:`PyModule_GetState`), or its contents (such as the module's
+:attr:`__dict__` or individual classes created with :c:func:`PyType_FromSpec`).
 
-   .. c:member:: char* m_name
+All modules created using multi-phase initialization are expected to support
+:ref:`sub-interpreters <sub-interpreter-support>`. Making sure multiple modules
+are independent is typically enough to achieve this.
 
-      Name for the new module.
+To request multi-phase initialization, the initialization function
+(PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty
+:c:member:`~PyModuleDef.m_slots`. Before it is returned, the ``PyModuleDef``
+instance must be initialized with the following function:
 
-   .. c:member:: char* m_doc
+.. c:function:: PyObject* PyModuleDef_Init(PyModuleDef *def)
 
-      Docstring for the module; usually a docstring variable created with
-      :c:func:`PyDoc_STRVAR` is used.
+   Ensures a module definition is a properly initialized Python object that
+   correctly reports its type and reference count.
 
-   .. c:member:: Py_ssize_t m_size
+   Returns *def* cast to ``PyObject*``, or *NULL* if an error occurred.
 
-      Some modules allow re-initialization (calling their ``PyInit_*`` function
-      more than once). These modules should keep their state in a per-module
-      memory area that can be retrieved with :c:func:`PyModule_GetState`.
+   .. versionadded:: 3.5
 
-      This memory should be used, rather than static globals, to hold per-module
-      state, since it is then safe for use in multiple sub-interpreters.  It is
-      freed when the module object is deallocated, after the :c:member:`m_free`
-      function has been called, if present.
+The *m_slots* member of the module definition must point to an array of
+``PyModuleDef_Slot`` structures:
 
-      Setting ``m_size`` to ``-1`` means that the module can not be
-      re-initialized because it has global state. Setting it to a non-negative
-      value means that the module can be re-initialized and specifies the
-      additional amount of memory it requires for its state.
+.. c:type:: PyModuleDef_Slot
 
-      See :PEP:`3121` for more details.
+   .. c:member:: int slot
 
-   .. c:member:: PyMethodDef* m_methods
+      A slot ID, chosen from the available values explained below.
 
-      A pointer to a table of module-level functions, described by
-      :c:type:`PyMethodDef` values.  Can be *NULL* if no functions are present.
+   .. c:member:: void* value
 
-   .. c:member:: inquiry m_reload
+      Value of the slot, whose meaning depends on the slot ID.
 
-      Currently unused, should be *NULL*.
+   .. versionadded:: 3.5
 
-   .. c:member:: traverseproc m_traverse
+The *m_slots* array must be terminated by a slot with id 0.
 
-      A traversal function to call during GC traversal of the module object, or
-      *NULL* if not needed.
+The available slot types are:
 
-   .. c:member:: inquiry m_clear
+.. c:var:: Py_mod_create
 
-      A clear function to call during GC clearing of the module object, or
-      *NULL* if not needed.
+   Specifies a function that is called to create the module object itself.
+   The *value* pointer of this slot must point to a function of the signature:
 
-   .. c:member:: freefunc m_free
+   .. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
 
-      A function to call during deallocation of the module object, or *NULL* if
-      not needed.
+   The function receives a :py:class:`~importlib.machinery.ModuleSpec`
+   instance, as defined in :PEP:`451`, and the module definition.
+   It should return a new module object, or set an error
+   and return *NULL*.
+
+   This function should be kept minimal. In particular, it should not
+   call arbitrary Python code, as trying to import the same module again may
+   result in an infinite loop.
+
+   Multiple ``Py_mod_create`` slots may not be specified in one module
+   definition.
+
+   If ``Py_mod_create`` is not specified, the import machinery will create
+   a normal module object using :c:func:`PyModule_New`. The name is taken from
+   *spec*, not the definition, to allow extension modules to dynamically adjust
+   to their place in the module hierarchy and be imported under different
+   names through symlinks, all while sharing a single module definition.
+
+   There is no requirement for the returned object to be an instance of
+   :c:type:`PyModule_Type`. Any type can be used, as long as it supports
+   setting and getting import-related attributes.
+   However, only ``PyModule_Type`` instances may be returned if the
+   ``PyModuleDef`` has non-*NULL* ``m_methods``, ``m_traverse``, ``m_clear``,
+   ``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``.
+
+.. c:var:: Py_mod_exec
+
+   Specifies a function that is called to *execute* the module.
+   This is equivalent to executing the code of a Python module: typically,
+   this function adds classes and constants to the module.
+   The signature of the function is:
+
+   .. c:function:: int exec_module(PyObject* module)
+
+   If multiple ``Py_mod_exec`` slots are specified, they are processed in the
+   order they appear in the *m_slots* array.
+
+See :PEP:`489` for more details on multi-phase initialization.
+
+Low-level module creation functions
+...................................
+
+The following functions are called under the hood when using multi-phase
+initialization. They can be used directly, for example when creating module
+objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
+``PyModule_ExecDef`` must be called to fully initialize a module.
+
+.. c:function:: PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
+
+   Create a new module object, given the definition in *module* and the
+   ModuleSpec *spec*.  This behaves like :c:func:`PyModule_FromDefAndSpec2`
+   with *module_api_version* set to :const:`PYTHON_API_VERSION`.
+
+   .. versionadded:: 3.5
+
+.. c:function:: PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
+
+   Create a new module object, given the definition in *module* and the
+   ModuleSpec *spec*, assuming the API version *module_api_version*.
+   If that version does not match the version of the running interpreter,
+   a :exc:`RuntimeWarning` is emitted.
+
+   .. note::
 
+      Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec`
+      instead; only use this if you are sure you need it.
+
+   .. versionadded:: 3.5
+
+.. c:function:: int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
+
+   Process any execution slots (:c:data:`Py_mod_exec`) given in *def*.
+
+   .. versionadded:: 3.5
+
+.. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)
+
+   Set the docstring for *module* to *docstring*.
+   This function is called automatically when creating a module from
+   ``PyModuleDef``, using either ``PyModule_Create`` or
+   ``PyModule_FromDefAndSpec``.
+
+   .. versionadded:: 3.5
+
+.. c:function:: int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
+
+   Add the functions from the *NULL* terminated *functions* array to *module*.
+   Refer to the :c:type:`PyMethodDef` documentation for details on individual
+   entries (due to the lack of a shared module namespace, module level
+   "functions" implemented in C typically receive the module as their first
+   parameter, making them similar to instance methods on Python classes).
+   This function is called automatically when creating a module from
+   ``PyModuleDef``, using either ``PyModule_Create`` or
+   ``PyModule_FromDefAndSpec``.
+
+   .. versionadded:: 3.5
+
+Support functions
+.................
+
+The module initialization function (if using single phase initialization) or
+a function called from a module execution slot (if using multi-phase
+initialization), can use the following functions to help initialize the module
+state:
 
 .. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
 
@@ -236,7 +410,6 @@ These functions are usually used in the module initialization function.
    be used from the module's initialization function.  This steals a reference to
    *value*.  Return ``-1`` on error, ``0`` on success.
 
-
 .. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
 
    Add an integer constant to *module* as *name*.  This convenience function can be
@@ -248,7 +421,7 @@ These functions are usually used in the module initialization function.
 
    Add a string constant to *module* as *name*.  This convenience function can be
    used from the module's initialization function.  The string *value* must be
-   null-terminated.  Return ``-1`` on error, ``0`` on success.
+   *NULL*-terminated.  Return ``-1`` on error, ``0`` on success.
 
 
 .. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
@@ -262,3 +435,36 @@ These functions are usually used in the module initialization function.
 .. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
 
    Add a string constant to *module*.
+
+
+Module lookup
+^^^^^^^^^^^^^
+
+Single-phase initialization creates singleton modules that can be looked up
+in the context of the current interpreter. This allows the module object to be
+retrieved later with only a reference to the module definition.
+
+These functions will not work on modules created using multi-phase initialization,
+since multiple such modules can be created from a single definition.
+
+.. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
+
+   Returns the module object that was created from *def* for the current interpreter.
+   This method requires that the module object has been attached to the interpreter state with
+   :c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
+   found or has not been attached to the interpreter state yet, it returns *NULL*.
+
+.. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def)
+
+   Attaches the module object passed to the function to the interpreter state. This allows
+   the module object to be accessible via :c:func:`PyState_FindModule`.
+
+   Only effective on modules created using single-phase initialization.
+
+   .. versionadded:: 3.3
+
+.. c:function:: int PyState_RemoveModule(PyModuleDef *def)
+
+   Removes the module object created from *def* from the interpreter state.
+
+   .. versionadded:: 3.3
diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst
index 21951c38c0..9bcb649c9d 100644
--- a/Doc/c-api/number.rst
+++ b/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.
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 7cead07081..3d83b279c2 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -47,6 +47,60 @@ Operating System Utilities
    not call those functions directly!  :c:type:`PyOS_sighandler_t` is a typedef
    alias for :c:type:`void (\*)(int)`.
 
+.. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size)
+
+   Decode a byte string from the locale encoding with the :ref:`surrogateescape
+   error handler <surrogateescape>`: undecodable bytes are decoded as
+   characters in range U+DC80..U+DCFF. If a byte sequence can be decoded as a
+   surrogate character, escape the bytes using the surrogateescape error
+   handler instead of decoding them.
+
+   Return a pointer to a newly allocated wide character string, use
+   :c:func:`PyMem_RawFree` to free the memory. If size is not ``NULL``, write
+   the number of wide characters excluding the null character into ``*size``
+
+   Return ``NULL`` on decoding error or memory allocation error. If *size* is
+   not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to
+   ``(size_t)-2`` on decoding error.
+
+   Decoding errors should never happen, unless there is a bug in the C
+   library.
+
+   Use the :c:func:`Py_EncodeLocale` function to encode the character string
+   back to a byte string.
+
+   .. seealso::
+
+      The :c:func:`PyUnicode_DecodeFSDefaultAndSize` and
+      :c:func:`PyUnicode_DecodeLocaleAndSize` functions.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
+
+   Encode a wide character string to the locale encoding with the
+   :ref:`surrogateescape error handler <surrogateescape>`: surrogate characters
+   in the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF.
+
+   Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free`
+   to free the memory. Return ``NULL`` on encoding error or memory allocation
+   error
+
+   If error_pos is not ``NULL``, ``*error_pos`` is set to the index of the
+   invalid character on encoding error, or set to ``(size_t)-1`` otherwise.
+
+   Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back
+   to a wide character string.
+
+   .. seealso::
+
+      The :c:func:`PyUnicode_EncodeFSDefault` and
+      :c:func:`PyUnicode_EncodeLocale` functions.
+
+   .. versionadded:: 3.5
+
+
 .. _systemfunctions:
 
 System Functions
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 5de8be0680..b5113aaef1 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -220,9 +220,14 @@ type objects) *must* have the :attr:`ob_size` field.
    the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*.
 
 
-.. c:member:: void* PyTypeObject.tp_reserved
+.. c:member:: PyAsyncMethods* tp_as_async
 
-   Reserved slot, formerly known as tp_compare.
+   Pointer to an additional structure that contains fields relevant only to
+   objects which implement :term:`awaitable` and :term:`asynchronous iterator`
+   protocols at the C-level.  See :ref:`async-structs` for details.
+
+   .. versionadded:: 3.5
+      Formerly known as ``tp_compare`` and ``tp_reserved``.
 
 
 .. c:member:: reprfunc PyTypeObject.tp_repr
@@ -1118,6 +1123,9 @@ Number Object Structures
             binaryfunc nb_inplace_true_divide;
 
             unaryfunc nb_index;
+
+            binaryfunc nb_matrix_multiply;
+            binaryfunc nb_inplace_matrix_multiply;
        } PyNumberMethods;
 
    .. note::
@@ -1329,3 +1337,58 @@ Buffer Object Structures
 
    :c:func:`PyBuffer_Release` is the interface for the consumer that
    wraps this function.
+
+
+.. _async-structs:
+
+
+Async Object Structures
+=======================
+
+.. sectionauthor:: Yury Selivanov <yselivanov@sprymix.com>
+
+.. versionadded:: 3.5
+
+.. c:type:: PyAsyncMethods
+
+   This structure holds pointers to the functions required to implement
+   :term:`awaitable` and :term:`asynchronous iterator` objects.
+
+   Here is the structure definition::
+
+        typedef struct {
+            unaryfunc am_await;
+            unaryfunc am_aiter;
+            unaryfunc am_anext;
+        } PyAsyncMethods;
+
+.. c:member:: unaryfunc PyAsyncMethods.am_await
+
+   The signature of this function is::
+
+      PyObject *am_await(PyObject *self)
+
+   The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must
+   return ``1`` for it.
+
+   This slot may be set to *NULL* if an object is not an :term:`awaitable`.
+
+.. c:member:: unaryfunc PyAsyncMethods.am_aiter
+
+   The signature of this function is::
+
+      PyObject *am_aiter(PyObject *self)
+
+   Must return an :term:`awaitable` object.  See :meth:`__anext__` for details.
+
+   This slot may be set to *NULL* if an object does not implement
+   asynchronous iteration protocol.
+
+.. c:member:: unaryfunc PyAsyncMethods.am_anext
+
+   The signature of this function is::
+
+      PyObject *am_anext(PyObject *self)
+
+   Must return an :term:`awaitable` object.  See :meth:`__anext__` for details.
+   This slot may be set to *NULL*.
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index f7e99d6d99..2eeadb52c9 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -765,11 +765,13 @@ system.
    *errors* is ``NULL``.  *str* must end with a null character but
    cannot contain embedded null characters.
 
+   Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` to decode a string from
+   :c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
+   Python startup).
+
    .. seealso::
 
-      Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` to decode a string from
-      :c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
-      Python startup).
+      The :c:func:`Py_DecodeLocale` function.
 
    .. versionadded:: 3.3
 
@@ -790,11 +792,13 @@ system.
    *errors* is ``NULL``. Return a :class:`bytes` object. *str* cannot
    contain embedded null characters.
 
+   Use :c:func:`PyUnicode_EncodeFSDefault` to encode a string to
+   :c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
+   Python startup).
+
    .. seealso::
 
-      Use :c:func:`PyUnicode_EncodeFSDefault` to encode a string to
-      :c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
-      Python startup).
+      The :c:func:`Py_EncodeLocale` function.
 
    .. versionadded:: 3.3
 
@@ -839,12 +843,14 @@ used, passing :c:func:`PyUnicode_FSDecoder` as the conversion function:
    If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
    locale encoding.
 
+   :c:data:`Py_FileSystemDefaultEncoding` is initialized at startup from the
+   locale encoding and cannot be modified later. If you need to decode a string
+   from the current locale encoding, use
+   :c:func:`PyUnicode_DecodeLocaleAndSize`.
+
    .. seealso::
 
-      :c:data:`Py_FileSystemDefaultEncoding` is initialized at startup from the
-      locale encoding and cannot be modified later. If you need to decode a
-      string from the current locale encoding, use
-      :c:func:`PyUnicode_DecodeLocaleAndSize`.
+      The :c:func:`Py_DecodeLocale` function.
 
    .. versionchanged:: 3.2
       Use ``"strict"`` error handler on Windows.
@@ -874,12 +880,13 @@ used, passing :c:func:`PyUnicode_FSDecoder` as the conversion function:
    If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
    locale encoding.
 
+   :c:data:`Py_FileSystemDefaultEncoding` is initialized at startup from the
+   locale encoding and cannot be modified later. If you need to encode a string
+   to the current locale encoding, use :c:func:`PyUnicode_EncodeLocale`.
+
    .. seealso::
 
-      :c:data:`Py_FileSystemDefaultEncoding` is initialized at startup from the
-      locale encoding and cannot be modified later. If you need to encode a
-      string to the current locale encoding, use
-      :c:func:`PyUnicode_EncodeLocale`.
+      The :c:func:`Py_EncodeLocale` function.
 
    .. versionadded:: 3.2