Merge branch 'master' into pep585

Author: gvanrossum

Doc/c-api/call.rst

@@ -35,17 +35,11 @@ To call an object, use :c:func:`PyObject_Call` or other
 The Vectorcall Protocol
 -----------------------
 
-.. versionadded:: 3.8
+.. versionadded:: 3.9
 
 The vectorcall protocol was introduced in :pep:`590` as an additional protocol
 for making calls more efficient.
 
-.. warning::
-
-   The vectorcall API is provisional and expected to become public in
-   Python 3.9, with a different names and, possibly, changed semantics.
-   If you use the it, plan for updating your code for Python 3.9.
-
 As rule of thumb, CPython will prefer the vectorcall for internal calls
 if the callable supports it. However, this is not a hard rule.
 Additionally, some third-party extensions use *tp_call* directly
@@ -69,7 +63,7 @@ the arguments to an args tuple and kwargs dict anyway, then there is no point
 in implementing vectorcall.
 
 Classes can implement the vectorcall protocol by enabling the
-:const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
+:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
 :c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the
 object structure where a *vectorcallfunc* appears.
 This is a pointer to a function with the following signature:
@@ -97,7 +91,7 @@ This is a pointer to a function with the following signature:
    argument 1 (not 0) in the allocated vector.
    The callee must restore the value of ``args[-1]`` before returning.
 
-   For :c:func:`_PyObject_VectorcallMethod`, this flag means instead that
+   For :c:func:`PyObject_VectorcallMethod`, this flag means instead that
    ``args[0]`` may be changed.
 
    Whenever they can do so cheaply (without additional allocation), callers
@@ -107,7 +101,20 @@ This is a pointer to a function with the following signature:
 
 To call an object that implements vectorcall, use a :ref:`call API <capi-call>`
 function as with any other callable.
-:c:func:`_PyObject_Vectorcall` will usually be most efficient.
+:c:func:`PyObject_Vectorcall` will usually be most efficient.
+
+
+.. note::
+
+   In CPython 3.8, the vectorcall API and related functions were available
+   provisionally under names with a leading underscore:
+   ``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``,
+   ``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``,
+   ``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``,
+   ``_PyObject_CallMethodOneArg``.
+   Additionally, ``PyObject_VectorcallDict`` was available as
+   ``_PyObject_FastCallDict``.
+   The old names are still defined as aliases of the new, non-underscored names.
 
 
 Recursion Control
@@ -137,17 +144,21 @@ Vectorcall Support API
    However, the function ``PyVectorcall_NARGS`` should be used to allow
    for future extensions.
 
+   This function is not part of the `limited API <stable>`_.
+
    .. versionadded:: 3.8
 
-.. c:function:: vectorcallfunc _PyVectorcall_Function(PyObject *op)
+.. c:function:: vectorcallfunc PyVectorcall_Function(PyObject *op)
 
    If *op* does not support the vectorcall protocol (either because the type
    does not or because the specific instance does not), return *NULL*.
    Otherwise, return the vectorcall function pointer stored in *op*.
    This function never raises an exception.
 
    This is mostly useful to check whether or not *op* supports vectorcall,
-   which can be done by checking ``_PyVectorcall_Function(op) != NULL``.
+   which can be done by checking ``PyVectorcall_Function(op) != NULL``.
+
+   This function is not part of the `limited API <stable>`_.
 
    .. versionadded:: 3.8
 
@@ -158,9 +169,11 @@ Vectorcall Support API
 
    This is a specialized function, intended to be put in the
    :c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
-   It does not check the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag
+   It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
    and it does not fall back to ``tp_call``.
 
+   This function is not part of the `limited API <stable>`_.
+
    .. versionadded:: 3.8
 
 
@@ -185,7 +198,7 @@ please see individual documentation for details.
 +------------------------------------------+------------------+--------------------+---------------+
 | :c:func:`PyObject_CallNoArgs`            | ``PyObject *``   | ---                | ---           |
 +------------------------------------------+------------------+--------------------+---------------+
-| :c:func:`_PyObject_CallOneArg`           | ``PyObject *``   | 1 object           | ---           |
+| :c:func:`PyObject_CallOneArg`            | ``PyObject *``   | 1 object           | ---           |
 +------------------------------------------+------------------+--------------------+---------------+
 | :c:func:`PyObject_CallObject`            | ``PyObject *``   | tuple/``NULL``     | ---           |
 +------------------------------------------+------------------+--------------------+---------------+
@@ -197,15 +210,15 @@ please see individual documentation for details.
 +------------------------------------------+------------------+--------------------+---------------+
 | :c:func:`PyObject_CallMethodObjArgs`     | obj + name       | variadic           | ---           |
 +------------------------------------------+------------------+--------------------+---------------+
-| :c:func:`_PyObject_CallMethodNoArgs`     | obj + name       | ---                | ---           |
+| :c:func:`PyObject_CallMethodNoArgs`      | obj + name       | ---                | ---           |
 +------------------------------------------+------------------+--------------------+---------------+
-| :c:func:`_PyObject_CallMethodOneArg`     | obj + name       | 1 object           | ---           |
+| :c:func:`PyObject_CallMethodOneArg`      | obj + name       | 1 object           | ---           |
 +------------------------------------------+------------------+--------------------+---------------+
-| :c:func:`_PyObject_Vectorcall`           | ``PyObject *``   | vectorcall         | vectorcall    |
+| :c:func:`PyObject_Vectorcall`            | ``PyObject *``   | vectorcall         | vectorcall    |
 +------------------------------------------+------------------+--------------------+---------------+
-| :c:func:`_PyObject_FastCallDict`         | ``PyObject *``   | vectorcall         | dict/``NULL`` |
+| :c:func:`PyObject_VectorcallDict`        | ``PyObject *``   | vectorcall         | dict/``NULL`` |
 +------------------------------------------+------------------+--------------------+---------------+
-| :c:func:`_PyObject_VectorcallMethod`     | arg + name       | vectorcall         | vectorcall    |
+| :c:func:`PyObject_VectorcallMethod`      | arg + name       | vectorcall         | vectorcall    |
 +------------------------------------------+------------------+--------------------+---------------+
 
 
@@ -235,14 +248,16 @@ please see individual documentation for details.
    .. versionadded:: 3.9
 
 
-.. c:function:: PyObject* _PyObject_CallOneArg(PyObject *callable, PyObject *arg)
+.. c:function:: PyObject* PyObject_CallOneArg(PyObject *callable, PyObject *arg)
 
    Call a callable Python object *callable* with exactly 1 positional argument
    *arg* and no keyword arguments.
 
    Return the result of the call on success, or raise an exception and return
    *NULL* on failure.
 
+   This function is not part of the `limited API <stable>`_.
+
    .. versionadded:: 3.9
 
 
@@ -320,18 +335,20 @@ please see individual documentation for details.
    *NULL* on failure.
 
 
-.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
+.. c:function:: PyObject* PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
 
    Call a method of the Python object *obj* without arguments,
    where the name of the method is given as a Python string object in *name*.
 
    Return the result of the call on success, or raise an exception and return
    *NULL* on failure.
 
+   This function is not part of the `limited API <stable>`_.
+
    .. versionadded:: 3.9
 
 
-.. c:function:: PyObject* _PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
+.. c:function:: PyObject* PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
 
    Call a method of the Python object *obj* with a single positional argument
    *arg*, where the name of the method is given as a Python string object in
@@ -340,10 +357,12 @@ please see individual documentation for details.
    Return the result of the call on success, or raise an exception and return
    *NULL* on failure.
 
+   This function is not part of the `limited API <stable>`_.
+
    .. versionadded:: 3.9
 
 
-.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
+.. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
 
    Call a callable Python object *callable*.
    The arguments are the same as for :c:type:`vectorcallfunc`.
@@ -353,15 +372,11 @@ please see individual documentation for details.
    Return the result of the call on success, or raise an exception and return
    *NULL* on failure.
 
-   .. note::
-
-      This function is provisional and expected to become public in Python 3.9,
-      with a different name and, possibly, changed semantics.
-      If you use the function, plan for updating your code for Python 3.9.
+   This function is not part of the `limited API <stable>`_.
 
-   .. versionadded:: 3.8
+   .. versionadded:: 3.9
 
-.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
+.. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
 
    Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol,
    but with keyword arguments passed as a dictionary *kwdict*.
@@ -373,15 +388,11 @@ please see individual documentation for details.
    already has a dictionary ready to use for the keyword arguments,
    but not a tuple for the positional arguments.
 
-   .. note::
+   This function is not part of the `limited API <stable>`_.
 
-      This function is provisional and expected to become public in Python 3.9,
-      with a different name and, possibly, changed semantics.
-      If you use the function, plan for updating your code for Python 3.9.
-
-   .. versionadded:: 3.8
+   .. versionadded:: 3.9
 
-.. c:function:: PyObject* _PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
+.. c:function:: PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
 
    Call a method using the vectorcall calling convention. The name of the method
    is given as a Python string *name*. The object whose method is called is
@@ -390,7 +401,7 @@ please see individual documentation for details.
    *nargsf* is the number of positional arguments including *args[0]*,
    plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
    temporarily be changed. Keyword arguments can be passed just like in
-   :c:func:`_PyObject_Vectorcall`.
+   :c:func:`PyObject_Vectorcall`.
 
    If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
    this will call the unbound method object with the full
@@ -399,6 +410,8 @@ please see individual documentation for details.
    Return the result of the call on success, or raise an exception and return
    *NULL* on failure.
 
+   This function is not part of the `limited API <stable>`_.
+
    .. versionadded:: 3.9
 
 

Doc/c-api/init.rst

@@ -1048,6 +1048,10 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    Reset all information in a thread state object.  The global interpreter lock
    must be held.
 
+   .. versionchanged:: 3.9
+      This function now calls the :c:member:`PyThreadState.on_delete` callback.
+      Previously, that happened in :c:func:`PyThreadState_Delete`.
+
 
 .. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
 
@@ -1110,7 +1114,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
 .. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
 
    Acquire the global interpreter lock and set the current thread state to
-   *tstate*, which should not be ``NULL``.  The lock must have been created earlier.
+   *tstate*, which must not be ``NULL``.  The lock must have been created earlier.
    If this thread already has the lock, deadlock ensues.
 
    .. note::

Doc/c-api/init_config.rst

@@ -627,14 +627,6 @@ PyConfig
 
       ``python3 -m MODULE`` argument. Used by :c:func:`Py_RunMain`.
 
-   .. c:member:: int show_alloc_count
-
-      Show allocation counts at exit?
-
-      Set to 1 by :option:`-X showalloccount <-X>` command line option.
-
-      Need a special Python build with ``COUNT_ALLOCS`` macro defined.
-
    .. c:member:: int show_ref_count
 
       Show total reference count at exit?
@@ -702,6 +694,10 @@ arguments are stripped from ``argv``: see :ref:`Command Line Arguments
 The ``xoptions`` options are parsed to set other options: see :option:`-X`
 option.
 
+.. versionchanged:: 3.9
+
+   The ``show_alloc_count`` field has been removed.
+
 
 Initialization with PyConfig
 ----------------------------

Doc/c-api/structures.rst

@@ -70,6 +70,13 @@ the definition of all other Python objects.
       (((PyObject*)(o))->ob_type)
 
 
+.. c:function:: void Py_SET_TYPE(PyObject *o, PyTypeObject *type)
+
+   Set the object *o* type to *type*.
+
+   .. versionadded:: 3.9
+
+
 .. c:macro:: Py_REFCNT(o)
 
    This macro is used to access the :attr:`ob_refcnt` member of a Python
@@ -79,6 +86,13 @@ the definition of all other Python objects.
       (((PyObject*)(o))->ob_refcnt)
 
 
+.. c:function:: void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)
+
+   Set the object *o* reference counter to *refcnt*.
+
+   .. versionadded:: 3.9
+
+
 .. c:macro:: Py_SIZE(o)
 
    This macro is used to access the :attr:`ob_size` member of a Python object.
@@ -87,6 +101,13 @@ the definition of all other Python objects.
       (((PyVarObject*)(o))->ob_size)
 
 
+.. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
+
+   Set the object *o* size of *size*.
+
+   .. versionadded:: 3.9
+
+
 .. c:macro:: PyObject_HEAD_INIT(type)
 
    This is a macro which expands to initialization values for a new

Doc/c-api/type.rst

@@ -21,14 +21,14 @@ Type Objects
 
 .. c:function:: int PyType_Check(PyObject *o)
 
-   Return true if the object *o* is a type object, including instances of types
-   derived from the standard type object.  Return false in all other cases.
+   Return non-zero if the object *o* is a type object, including instances of
+   types derived from the standard type object.  Return 0 in all other cases.
 
 
 .. c:function:: int PyType_CheckExact(PyObject *o)
 
-   Return true if the object *o* is a type object, but not a subtype of the
-   standard type object.  Return false in all other cases.
+   Return non-zero if the object *o* is a type object, but not a subtype of the
+   standard type object.  Return 0 in all other cases.
 
 
 .. c:function:: unsigned int PyType_ClearCache()
@@ -57,8 +57,8 @@ Type Objects
 
 .. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature)
 
-   Return true if the type object *o* sets the feature *feature*.  Type features
-   are denoted by single bit flags.
+   Return non-zero if the type object *o* sets the feature *feature*.
+   Type features are denoted by single bit flags.
 
 
 .. c:function:: int PyType_IS_GC(PyTypeObject *o)