bpo-37337: Add _PyObject_VectorcallMethod() (GH-14228)

1 files changed, 22 insertions, 0 deletions

diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 13f13b3..a84235b 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -395,6 +395,9 @@ Object Protocol
    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
+   ``args[0]`` may be changed.
+
    Whenever they can do so cheaply (without additional allocation), callers
    are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
    Doing so will allow callables such as bound methods to make their onward
@@ -430,6 +433,25 @@ Object Protocol
 
    .. versionadded:: 3.8
 
+.. 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 Python string *name*. The object whose method is called is
+   *args[0]* and the *args* array starting at *args[1]* represents the arguments
+   of the call. There must be at least one positional argument.
+   *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`.
+
+   If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
+   this will actually call the unbound method object with the full
+   *args* vector as arguments.
+
+   Return the result of the call on success, or raise an exception and return
+   *NULL* on failure.
+
+   .. versionadded:: 3.9
 
 .. c:function:: Py_hash_t PyObject_Hash(PyObject *o)