bpo-39245: Make Vectorcall C API public (GH-17893)
* Add backcompat defines and move non-limited API declaration to cpython/
This partially reverts commit 2ff58a24e8a1c7e290d025d69ebaea0bbead3b8c
which added PyObject_CallNoArgs to the 3.9+ stable ABI. This should not
be done; there are enough other call APIs in the stable ABI to choose from.
* Adjust documentation
Mark all newly public functions as added in 3.9.
Add a note about the 3.8 provisional names.
Add notes on public API.
* Put PyObject_CallNoArgs back in the limited API
* Rename PyObject_FastCallDict to PyObject_VectorcallDict
diff --git a/Doc/c-api/call.rst b/Doc/c-api/call.rst
index 0833531..06db126 100644
--- a/Doc/c-api/call.rst
+++ b/Doc/c-api/call.rst
@@ -35,17 +35,11 @@
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 @@
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 @@
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 @@
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,9 +144,11 @@
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*.
@@ -147,7 +156,9 @@
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 @@
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 @@
+------------------------------------------+------------------+--------------------+---------------+
| :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 @@
+------------------------------------------+------------------+--------------------+---------------+
| :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,7 +248,7 @@
.. 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.
@@ -243,6 +256,8 @@
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,7 +335,7 @@
*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*.
@@ -328,10 +343,12 @@
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 @@
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 @@
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
- .. 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.9
- .. versionadded:: 3.8
-
-.. 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 @@
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.9
- .. versionadded:: 3.8
-
-.. 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 @@
*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 @@
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
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index a8a779e..ff0e70e 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -684,15 +684,15 @@
a more efficient alternative
of the simpler :c:member:`~PyTypeObject.tp_call`.
- This field is only used if the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL`
+ This field is only used if the flag :const:`Py_TPFLAGS_HAVE_VECTORCALL`
is set. If so, this must be a positive integer containing the offset in the
instance of a :c:type:`vectorcallfunc` pointer.
The *vectorcallfunc* pointer may be ``NULL``, in which case the instance behaves
- as if :const:`_Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
+ as if :const:`Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
falls back to :c:member:`~PyTypeObject.tp_call`.
- Any class that sets ``_Py_TPFLAGS_HAVE_VECTORCALL`` must also set
+ Any class that sets ``Py_TPFLAGS_HAVE_VECTORCALL`` must also set
:c:member:`~PyTypeObject.tp_call` and make sure its behaviour is consistent
with the *vectorcallfunc* function.
This can be done by setting *tp_call* to :c:func:`PyVectorcall_Call`.
@@ -719,7 +719,7 @@
**Inheritance:**
This field is always inherited.
- However, the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag is not
+ However, the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is not
always inherited. If it's not, then the subclass won't use
:ref:`vectorcall <vectorcall>`, except when
:c:func:`PyVectorcall_Call` is explicitly called.
@@ -1153,7 +1153,7 @@
type structure.
- .. data:: _Py_TPFLAGS_HAVE_VECTORCALL
+ .. data:: Py_TPFLAGS_HAVE_VECTORCALL
This bit is set when the class implements
the :ref:`vectorcall protocol <vectorcall>`.
@@ -1163,15 +1163,9 @@
This bit is inherited for *static* subtypes if
:c:member:`~PyTypeObject.tp_call` is also inherited.
- `Heap types`_ do not inherit ``_Py_TPFLAGS_HAVE_VECTORCALL``.
+ `Heap types`_ do not inherit ``Py_TPFLAGS_HAVE_VECTORCALL``.
- .. note::
-
- This flag is provisional and expected to become public in Python 3.9,
- with a different name and, possibly, changed semantics.
- If you use vectorcall, plan for updating your code for Python 3.9.
-
- .. versionadded:: 3.8
+ .. versionadded:: 3.9
.. c:member:: const char* PyTypeObject.tp_doc