bpo-28805: document METH_FASTCALL (GH-14079)

(cherry picked from commit 5600b5e1b24a3491e83f1b3038a7ea047a34c0bf)

Co-authored-by: Jeroen Demeyer <J.Demeyer@UGent.be>

2 files changed, 52 insertions, 12 deletions

diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index da45da1d3c..274beeef5d 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -114,10 +114,20 @@ the definition of all other Python objects.
 
 .. c:type:: PyCFunctionWithKeywords
 
-   Type of the functions used to implement Python callables in C that take
-   keyword arguments: they take three :c:type:`PyObject\*` parameters and return
-   one such value.  See :c:type:`PyCFunction` above for the meaning of the return
-   value.
+   Type of the functions used to implement Python callables in C
+   with signature :const:`METH_VARARGS | METH_KEYWORDS`.
+
+
+.. c:type:: _PyCFunctionFast
+
+   Type of the functions used to implement Python callables in C
+   with signature :const:`METH_FASTCALL`.
+
+
+.. c:type:: _PyCFunctionFastWithKeywords
+
+   Type of the functions used to implement Python callables in C
+   with signature :const:`METH_FASTCALL | METH_KEYWORDS`.
 
 
 .. c:type:: PyMethodDef
@@ -149,10 +159,11 @@ specific C type of the *self* object.
 
 The :attr:`ml_flags` field is a bitfield which can include the following flags.
 The individual flags indicate either a calling convention or a binding
-convention.  Of the calling convention flags, only :const:`METH_VARARGS` and
-:const:`METH_KEYWORDS` can be combined. Any of the calling convention flags
-can be combined with a binding flag.
+convention.
 
+There are four basic calling conventions for positional arguments
+and two of them can be combined with :const:`METH_KEYWORDS` to support
+also keyword arguments.  So there are a total of 6 calling conventions:
 
 .. data:: METH_VARARGS
 
@@ -164,13 +175,41 @@ can be combined with a binding flag.
    using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
 
 
-.. data:: METH_KEYWORDS
+.. data:: METH_VARARGS | METH_KEYWORDS
 
    Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
-   The function expects three parameters: *self*, *args*, and a dictionary of
-   all the keyword arguments.  The flag must be combined with
-   :const:`METH_VARARGS`, and the parameters are typically processed using
-   :c:func:`PyArg_ParseTupleAndKeywords`.
+   The function expects three parameters: *self*, *args*, *kwargs* where
+   *kwargs* is a dictionary of all the keyword arguments or possibly *NULL*
+   if there are no keyword arguments.  The parameters are typically processed
+   using :c:func:`PyArg_ParseTupleAndKeywords`.
+
+
+.. data:: METH_FASTCALL
+
+   Fast calling convention supporting only positional arguments.
+   The methods have the type :c:type:`_PyCFunctionFast`.
+   The first parameter is *self*, the second parameter is a C array
+   of :c:type:`PyObject\*` values indicating the arguments and the third
+   parameter is the number of arguments (the length of the array).
+
+   This is not part of the :ref:`limited API <stable>`.
+
+   .. versionadded:: 3.7
+
+
+.. data:: METH_FASTCALL | METH_KEYWORDS
+
+   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:
+   there is an additional fourth :c:type:`PyObject\*` parameter
+   which is a tuple representing the names of the keyword arguments
+   or possibly *NULL* if there are no keywords.  The values of the keyword
+   arguments are stored in the *args* array, after the positional arguments.
+
+   This is not part of the :ref:`limited API <stable>`.
+
+   .. versionadded:: 3.7
 
 
 .. data:: METH_NOARGS
diff --git a/Misc/NEWS.d/next/C API/2019-06-14-14-03-51.bpo-28805.qZC0N_.rst b/Misc/NEWS.d/next/C API/2019-06-14-14-03-51.bpo-28805.qZC0N_.rst
new file mode 100644
index 0000000000..6d6c4ad4af
--- /dev/null
+++ b/Misc/NEWS.d/next/C API/2019-06-14-14-03-51.bpo-28805.qZC0N_.rst
@@ -0,0 +1 @@
+The :const:`METH_FASTCALL` calling convention has been documented.