Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 5600b5e

Browse files
jdemeyermethane
authored andcommitted
bpo-28805: document METH_FASTCALL (GH-14079)
1 parent 2dfeaa9 commit 5600b5e

2 files changed

Lines changed: 52 additions & 12 deletions

File tree

Doc/c-api/structures.rst

Lines changed: 51 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -114,10 +114,20 @@ the definition of all other Python objects.
114114

115115
.. c:type:: PyCFunctionWithKeywords
116116
117-
Type of the functions used to implement Python callables in C that take
118-
keyword arguments: they take three :c:type:`PyObject\*` parameters and return
119-
one such value. See :c:type:`PyCFunction` above for the meaning of the return
120-
value.
117+
Type of the functions used to implement Python callables in C
118+
with signature :const:`METH_VARARGS | METH_KEYWORDS`.
119+
120+
121+
.. c:type:: _PyCFunctionFast
122+
123+
Type of the functions used to implement Python callables in C
124+
with signature :const:`METH_FASTCALL`.
125+
126+
127+
.. c:type:: _PyCFunctionFastWithKeywords
128+
129+
Type of the functions used to implement Python callables in C
130+
with signature :const:`METH_FASTCALL | METH_KEYWORDS`.
121131

122132

123133
.. c:type:: PyMethodDef
@@ -149,10 +159,11 @@ specific C type of the *self* object.
149159

150160
The :attr:`ml_flags` field is a bitfield which can include the following flags.
151161
The individual flags indicate either a calling convention or a binding
152-
convention. Of the calling convention flags, only :const:`METH_VARARGS` and
153-
:const:`METH_KEYWORDS` can be combined. Any of the calling convention flags
154-
can be combined with a binding flag.
162+
convention.
155163

164+
There are four basic calling conventions for positional arguments
165+
and two of them can be combined with :const:`METH_KEYWORDS` to support
166+
also keyword arguments. So there are a total of 6 calling conventions:
156167

157168
.. data:: METH_VARARGS
158169

@@ -164,13 +175,41 @@ can be combined with a binding flag.
164175
using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
165176

166177

167-
.. data:: METH_KEYWORDS
178+
.. data:: METH_VARARGS | METH_KEYWORDS
168179

169180
Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
170-
The function expects three parameters: *self*, *args*, and a dictionary of
171-
all the keyword arguments. The flag must be combined with
172-
:const:`METH_VARARGS`, and the parameters are typically processed using
173-
:c:func:`PyArg_ParseTupleAndKeywords`.
181+
The function expects three parameters: *self*, *args*, *kwargs* where
182+
*kwargs* is a dictionary of all the keyword arguments or possibly *NULL*
183+
if there are no keyword arguments. The parameters are typically processed
184+
using :c:func:`PyArg_ParseTupleAndKeywords`.
185+
186+
187+
.. data:: METH_FASTCALL
188+
189+
Fast calling convention supporting only positional arguments.
190+
The methods have the type :c:type:`_PyCFunctionFast`.
191+
The first parameter is *self*, the second parameter is a C array
192+
of :c:type:`PyObject\*` values indicating the arguments and the third
193+
parameter is the number of arguments (the length of the array).
194+
195+
This is not part of the :ref:`limited API <stable>`.
196+
197+
.. versionadded:: 3.7
198+
199+
200+
.. data:: METH_FASTCALL | METH_KEYWORDS
201+
202+
Extension of :const:`METH_FASTCALL` supporting also keyword arguments,
203+
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
204+
Keyword arguments are passed the same way as in the vectorcall protocol:
205+
there is an additional fourth :c:type:`PyObject\*` parameter
206+
which is a tuple representing the names of the keyword arguments
207+
or possibly *NULL* if there are no keywords. The values of the keyword
208+
arguments are stored in the *args* array, after the positional arguments.
209+
210+
This is not part of the :ref:`limited API <stable>`.
211+
212+
.. versionadded:: 3.7
174213

175214

176215
.. data:: METH_NOARGS
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
The :const:`METH_FASTCALL` calling convention has been documented.

0 commit comments

Comments
 (0)