bpo-36974: expand call protocol documentation

Doc/c-api/abstract.rst

@@ -18,6 +18,7 @@ but whose items have not been set to some non-\ ``NULL`` value yet.
 .. toctree::
 
    object.rst
+   call.rst
    number.rst
    sequence.rst
    mapping.rst

Doc/c-api/exceptions.rst

@@ -697,13 +697,17 @@ The following functions are used to create and modify Unicode exceptions from C.
    ``0`` on success, ``-1`` on failure.
 
 
+.. _recursion:
+
 Recursion Control
 =================
 
 These two functions provide a way to perform safe recursive calls at the C
 level, both in the core and in extension modules.  They are needed if the
 recursive code does not necessarily invoke Python code (which tracks its
 recursion depth automatically).
+They are also not needed for *tp_call* implementations
+because the :ref:`call protocol <call>` takes care of recursion handling.
 
 .. c:function:: int Py_EnterRecursiveCall(const char *where)
 

Doc/c-api/object.rst

@@ -248,246 +248,6 @@ Object Protocol
    of base classes).
 
 
-.. c:function:: int PyCallable_Check(PyObject *o)
-
-   Determine if the object *o* is callable.  Return ``1`` if the object is callable
-   and ``0`` otherwise.  This function always succeeds.
-
-
-.. c:function:: PyObject* PyObject_CallNoArgs(PyObject *callable)
-
-   Call a callable Python object *callable* without any arguments. It is the
-   most efficient way to call a callable Python object without any argument.
-
-   Return the result of the call on success, or raise an exception and return
-   ``NULL`` on failure.
-
-   .. versionadded:: 3.9
-
-
-.. 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.
-
-   .. versionadded:: 3.9
-
-
-.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
-
-   Call a callable Python object *callable*, with arguments given by the
-   tuple *args*, and named arguments given by the dictionary *kwargs*.
-
-   *args* must not be ``NULL``, use an empty tuple if no arguments are needed.
-   If no named arguments are needed, *kwargs* can be ``NULL``.
-
-   Return the result of the call on success, or raise an exception and return
-   ``NULL`` on failure.
-
-   This is the equivalent of the Python expression:
-   ``callable(*args, **kwargs)``.
-
-
-.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
-
-   Call a callable Python object *callable*, with arguments given by the
-   tuple *args*.  If no arguments are needed, then *args* can be ``NULL``.
-
-   Return the result of the call on success, or raise an exception and return
-   ``NULL`` on failure.
-
-   This is the equivalent of the Python expression: ``callable(*args)``.
-
-
-.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
-
-   Call a callable Python object *callable*, with a variable number of C arguments.
-   The C arguments are described using a :c:func:`Py_BuildValue` style format
-   string.  The format can be ``NULL``, indicating that no arguments are provided.
-
-   Return the result of the call on success, or raise an exception and return
-   ``NULL`` on failure.
-
-   This is the equivalent of the Python expression: ``callable(*args)``.
-
-   Note that if you only pass :c:type:`PyObject \*` args,
-   :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
-
-   .. versionchanged:: 3.4
-      The type of *format* was changed from ``char *``.
-
-
-.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
-
-   Call the method named *name* of object *obj* with a variable number of C
-   arguments.  The C arguments are described by a :c:func:`Py_BuildValue` format
-   string that should  produce a tuple.
-
-   The format can be ``NULL``, indicating that no arguments are provided.
-
-   Return the result of the call on success, or raise an exception and return
-   ``NULL`` on failure.
-
-   This is the equivalent of the Python expression:
-   ``obj.name(arg1, arg2, ...)``.
-
-   Note that if you only pass :c:type:`PyObject \*` args,
-   :c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
-
-   .. versionchanged:: 3.4
-      The types of *name* and *format* were changed from ``char *``.
-
-
-.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
-
-   Call a callable Python object *callable*, with a variable number of
-   :c:type:`PyObject\*` arguments.  The arguments are provided as a variable number
-   of parameters followed by ``NULL``.
-
-   Return the result of the call on success, or raise an exception and return
-   ``NULL`` on failure.
-
-   This is the equivalent of the Python expression:
-   ``callable(arg1, arg2, ...)``.
-
-
-.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)
-
-   Calls a method of the Python object *obj*, where the name of the method is given as a
-   Python string object in *name*.  It is called with a variable number of
-   :c:type:`PyObject\*` arguments.  The arguments are provided as a variable number
-   of parameters followed by ``NULL``.
-
-   Return the result of the call on success, or raise an exception and return
-   ``NULL`` on failure.
-
-
-.. 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.
-
-   .. versionadded:: 3.9
-
-
-.. 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
-   *name*.
-
-   Return the result of the call on success, or raise an exception and return
-   ``NULL`` on failure.
-
-   .. versionadded:: 3.9
-
-
-.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
-
-   Call a callable Python object *callable*, using
-   :c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>` if possible.
-
-   *args* is a C array with the positional arguments.
-
-   *nargsf* is the number of positional arguments plus optionally the flag
-   :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` (see below).
-   To get actual number of arguments, use
-   :c:func:`PyVectorcall_NARGS(nargsf) <PyVectorcall_NARGS>`.
-
-   *kwnames* can be either ``NULL`` (no keyword arguments) or a tuple of keyword
-   names, which must be strings. In the latter case, the values of the keyword
-   arguments are stored in *args* after the positional arguments.
-   The number of keyword arguments does not influence *nargsf*.
-
-   *kwnames* must contain only objects of type ``str`` (not a subclass),
-   and all keys must be unique.
-
-   Return the result of the call on success, or raise an exception and return
-   ``NULL`` on failure.
-
-   This uses the vectorcall protocol if the callable supports it;
-   otherwise, the arguments are converted to use
-   :c:member:`~PyTypeObject.tp_call`.
-
-   .. 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.
-
-   .. versionadded:: 3.8
-
-.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET
-
-   If set in a vectorcall *nargsf* argument, the callee is allowed to
-   temporarily change ``args[-1]``. In other words, *args* points to
-   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
-   calls (which include a prepended *self* argument) cheaply.
-
-   .. versionadded:: 3.8
-
-.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf)
-
-   Given a vectorcall *nargsf* argument, return the actual number of
-   arguments.
-   Currently equivalent to ``nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET``.
-
-   .. versionadded:: 3.8
-
-.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
-
-   Same as :c:func:`_PyObject_Vectorcall` except that the keyword arguments
-   are passed as a dictionary in *kwdict*. This may be ``NULL`` if there
-   are no keyword arguments.
-
-   For callables supporting :c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>`,
-   the arguments are internally converted to the vectorcall convention.
-   Therefore, this function adds some overhead compared to
-   :c:func:`_PyObject_Vectorcall`.
-   It should only be used if the caller already has a dictionary ready to use.
-
-   .. 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.
-
-   .. 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)
 
    .. index:: builtin: hash

Doc/c-api/structures.rst

@@ -208,7 +208,8 @@ also keyword arguments.  So there are a total of 6 calling conventions:
 
    Extension of :const:`METH_FASTCALL` supporting also keyword arguments,
    with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
-   Keyword arguments are passed the same way as in the vectorcall protocol:
+   Keyword arguments are passed the same way as in the
+   :ref:`vectorcall protocol <vectorcall>`:
    there is an additional fourth :c:type:`PyObject\*` parameter
    which is a tuple representing the names of the keyword arguments
    (which are guaranteed to be strings)

Doc/c-api/type.rst

@@ -193,6 +193,7 @@ The following functions and structs are used to create
         (see :ref:`PyMemberDef <pymemberdef-offsets>`)
       * :c:member:`~PyTypeObject.tp_dictoffset`
         (see :ref:`PyMemberDef <pymemberdef-offsets>`)
+      * :c:member:`~PyTypeObject.tp_vectorcall_offset`
       * :c:member:`~PyBufferProcs.bf_getbuffer`
       * :c:member:`~PyBufferProcs.bf_releasebuffer`