Debian Codegraph @

Doc/c-api/call.rst

raw
1 .. highlight:: c
2
3 .. _call:
4
5 Call Protocol
6 =============
7
8 CPython supports two different calling protocols:
9 *tp_call* and vectorcall.
10
11 The *tp_call* Protocol
12 ----------------------
13
14 Instances of classes that set :c:member:`~PyTypeObject.tp_call` are callable.
15 The signature of the slot is::
16
17 PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);
18
19 A call is made using a tuple for the positional arguments
20 and a dict for the keyword arguments, similarly to
21 ``callable(*args, **kwargs)`` in Python code.
22 *args* must be non-NULL (use an empty tuple if there are no arguments)
23 but *kwargs* may be *NULL* if there are no keyword arguments.
24
25 This convention is not only used by *tp_call*:
26 :c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_init`
27 also pass arguments this way.
28
29 To call an object, use :c:func:`PyObject_Call` or another
30 :ref:`call API <capi-call>`.
31
32
33 .. _vectorcall:
34
35 The Vectorcall Protocol
36 -----------------------
37
38 .. versionadded:: 3.9
39
40 The vectorcall protocol was introduced in :pep:`590` as an additional protocol
41 for making calls more efficient.
42
43 As rule of thumb, CPython will prefer the vectorcall for internal calls
44 if the callable supports it. However, this is not a hard rule.
45 Additionally, some third-party extensions use *tp_call* directly
46 (rather than using :c:func:`PyObject_Call`).
47 Therefore, a class supporting vectorcall must also implement
48 :c:member:`~PyTypeObject.tp_call`.
49 Moreover, the callable must behave the same
50 regardless of which protocol is used.
51 The recommended way to achieve this is by setting
52 :c:member:`~PyTypeObject.tp_call` to :c:func:`PyVectorcall_Call`.
53 This bears repeating:
54
55 .. warning::
56
57 A class supporting vectorcall **must** also implement
58 :c:member:`~PyTypeObject.tp_call` with the same semantics.
59
60 .. versionchanged:: 3.12
61
62 The :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
63 when the class's :py:meth:`~object.__call__` method is reassigned.
64 (This internally sets :c:member:`~PyTypeObject.tp_call` only, and thus
65 may make it behave differently than the vectorcall function.)
66 In earlier Python versions, vectorcall should only be used with
67 :c:macro:`immutable <Py_TPFLAGS_IMMUTABLETYPE>` or static types.
68
69 A class should not implement vectorcall if that would be slower
70 than *tp_call*. For example, if the callee needs to convert
71 the arguments to an args tuple and kwargs dict anyway, then there is no point
72 in implementing vectorcall.
73
74 Classes can implement the vectorcall protocol by enabling the
75 :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
76 :c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the
77 object structure where a *vectorcallfunc* appears.
78 This is a pointer to a function with the following signature:
79
80 .. c:type:: PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
81
82 - *callable* is the object being called.
83 - *args* is a C array consisting of the positional arguments followed by the
84 values of the keyword arguments.
85 This can be *NULL* if there are no arguments.
86 - *nargsf* is the number of positional arguments plus possibly the
87 :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
88 To get the actual number of positional arguments from *nargsf*,
89 use :c:func:`PyVectorcall_NARGS`.
90 - *kwnames* is a tuple containing the names of the keyword arguments;
91 in other words, the keys of the kwargs dict.
92 These names must be strings (instances of ``str`` or a subclass)
93 and they must be unique.
94 If there are no keyword arguments, then *kwnames* can instead be *NULL*.
95
96 .. c:macro:: PY_VECTORCALL_ARGUMENTS_OFFSET
97
98 If this flag is set in a vectorcall *nargsf* argument, the callee is allowed
99 to temporarily change ``args[-1]``. In other words, *args* points to
100 argument 1 (not 0) in the allocated vector.
101 The callee must restore the value of ``args[-1]`` before returning.
102
103 For :c:func:`PyObject_VectorcallMethod`, this flag means instead that
104 ``args[0]`` may be changed.
105
106 Whenever they can do so cheaply (without additional allocation), callers
107 are encouraged to use :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
108 Doing so will allow callables such as bound methods to make their onward
109 calls (which include a prepended *self* argument) very efficiently.
110
111 .. versionadded:: 3.8
112
113 To call an object that implements vectorcall, use a :ref:`call API <capi-call>`
114 function as with any other callable.
115 :c:func:`PyObject_Vectorcall` will usually be most efficient.
116
117
118 Recursion Control
119 .................
120
121 When using *tp_call*, callees do not need to worry about
122 :ref:`recursion <recursion>`: CPython uses
123 :c:func:`Py_EnterRecursiveCall` and :c:func:`Py_LeaveRecursiveCall`
124 for calls made using *tp_call*.
125
126 For efficiency, this is not the case for calls done using vectorcall:
127 the callee should use *Py_EnterRecursiveCall* and *Py_LeaveRecursiveCall*
128 if needed.
129
130
131 Vectorcall Support API
132 ......................
133
134 .. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf)
135
136 Given a vectorcall *nargsf* argument, return the actual number of
137 arguments.
138 Currently equivalent to::
139
140 (Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)
141
142 However, the function ``PyVectorcall_NARGS`` should be used to allow
143 for future extensions.
144
145 .. versionadded:: 3.8
146
147 .. c:function:: vectorcallfunc PyVectorcall_Function(PyObject *op)
148
149 If *op* does not support the vectorcall protocol (either because the type
150 does not or because the specific instance does not), return *NULL*.
151 Otherwise, return the vectorcall function pointer stored in *op*.
152 This function never raises an exception.
153
154 This is mostly useful to check whether or not *op* supports vectorcall,
155 which can be done by checking ``PyVectorcall_Function(op) != NULL``.
156
157 .. versionadded:: 3.9
158
159 .. c:function:: PyObject* PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)
160
161 Call *callable*'s :c:type:`vectorcallfunc` with positional and keyword
162 arguments given in a tuple and dict, respectively.
163
164 This is a specialized function, intended to be put in the
165 :c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
166 It does not check the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag
167 and it does not fall back to ``tp_call``.
168
169 .. versionadded:: 3.8
170
171
172 .. _capi-call:
173
174 Object Calling API
175 ------------------
176
177 Various functions are available for calling a Python object.
178 Each converts its arguments to a convention supported by the called object –
179 either *tp_call* or vectorcall.
180 In order to do as little conversion as possible, pick one that best fits
181 the format of data you have available.
182
183 The following table summarizes the available functions;
184 please see individual documentation for details.
185
186 +------------------------------------------+------------------+--------------------+---------------+
187 | Function | callable | args | kwargs |
188 +==========================================+==================+====================+===============+
189 | :c:func:`PyObject_Call` | ``PyObject *`` | tuple | dict/``NULL`` |
190 +------------------------------------------+------------------+--------------------+---------------+
191 | :c:func:`PyObject_CallNoArgs` | ``PyObject *`` | --- | --- |
192 +------------------------------------------+------------------+--------------------+---------------+
193 | :c:func:`PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- |
194 +------------------------------------------+------------------+--------------------+---------------+
195 | :c:func:`PyObject_CallObject` | ``PyObject *`` | tuple/``NULL`` | --- |
196 +------------------------------------------+------------------+--------------------+---------------+
197 | :c:func:`PyObject_CallFunction` | ``PyObject *`` | format | --- |
198 +------------------------------------------+------------------+--------------------+---------------+
199 | :c:func:`PyObject_CallMethod` | obj + ``char*`` | format | --- |
200 +------------------------------------------+------------------+--------------------+---------------+
201 | :c:func:`PyObject_CallFunctionObjArgs` | ``PyObject *`` | variadic | --- |
202 +------------------------------------------+------------------+--------------------+---------------+
203 | :c:func:`PyObject_CallMethodObjArgs` | obj + name | variadic | --- |
204 +------------------------------------------+------------------+--------------------+---------------+
205 | :c:func:`PyObject_CallMethodNoArgs` | obj + name | --- | --- |
206 +------------------------------------------+------------------+--------------------+---------------+
207 | :c:func:`PyObject_CallMethodOneArg` | obj + name | 1 object | --- |
208 +------------------------------------------+------------------+--------------------+---------------+
209 | :c:func:`PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall |
210 +------------------------------------------+------------------+--------------------+---------------+
211 | :c:func:`PyObject_VectorcallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` |
212 +------------------------------------------+------------------+--------------------+---------------+
213 | :c:func:`PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall |
214 +------------------------------------------+------------------+--------------------+---------------+
215
216
217 .. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
218
219 Call a callable Python object *callable*, with arguments given by the
220 tuple *args*, and named arguments given by the dictionary *kwargs*.
221
222 *args* must not be *NULL*; use an empty tuple if no arguments are needed.
223 If no named arguments are needed, *kwargs* can be *NULL*.
224
225 Return the result of the call on success, or raise an exception and return
226 *NULL* on failure.
227
228 This is the equivalent of the Python expression:
229 ``callable(*args, **kwargs)``.
230
231
232 .. c:function:: PyObject* PyObject_CallNoArgs(PyObject *callable)
233
234 Call a callable Python object *callable* without any arguments. It is the
235 most efficient way to call a callable Python object without any argument.
236
237 Return the result of the call on success, or raise an exception and return
238 *NULL* on failure.
239
240 .. versionadded:: 3.9
241
242
243 .. c:function:: PyObject* PyObject_CallOneArg(PyObject *callable, PyObject *arg)
244
245 Call a callable Python object *callable* with exactly 1 positional argument
246 *arg* and no keyword arguments.
247
248 Return the result of the call on success, or raise an exception and return
249 *NULL* on failure.
250
251 .. versionadded:: 3.9
252
253
254 .. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
255
256 Call a callable Python object *callable*, with arguments given by the
257 tuple *args*. If no arguments are needed, then *args* can be *NULL*.
258
259 Return the result of the call on success, or raise an exception and return
260 *NULL* on failure.
261
262 This is the equivalent of the Python expression: ``callable(*args)``.
263
264
265 .. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
266
267 Call a callable Python object *callable*, with a variable number of C arguments.
268 The C arguments are described using a :c:func:`Py_BuildValue` style format
269 string. The format can be *NULL*, indicating that no arguments are provided.
270
271 Return the result of the call on success, or raise an exception and return
272 *NULL* on failure.
273
274 This is the equivalent of the Python expression: ``callable(*args)``.
275
276 Note that if you only pass :c:expr:`PyObject *` args,
277 :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
278
279 .. versionchanged:: 3.4
280 The type of *format* was changed from ``char *``.
281
282
283 .. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
284
285 Call the method named *name* of object *obj* with a variable number of C
286 arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
287 string that should produce a tuple.
288
289 The format can be *NULL*, indicating that no arguments are provided.
290
291 Return the result of the call on success, or raise an exception and return
292 *NULL* on failure.
293
294 This is the equivalent of the Python expression:
295 ``obj.name(arg1, arg2, ...)``.
296
297 Note that if you only pass :c:expr:`PyObject *` args,
298 :c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
299
300 .. versionchanged:: 3.4
301 The types of *name* and *format* were changed from ``char *``.
302
303
304 .. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...)
305
306 Call a callable Python object *callable*, with a variable number of
307 :c:expr:`PyObject *` arguments. The arguments are provided as a variable number
308 of parameters followed by *NULL*.
309
310 Return the result of the call on success, or raise an exception and return
311 *NULL* on failure.
312
313 This is the equivalent of the Python expression:
314 ``callable(arg1, arg2, ...)``.
315
316
317 .. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)
318
319 Call a method of the Python object *obj*, where the name of the method is given as a
320 Python string object in *name*. It is called with a variable number of
321 :c:expr:`PyObject *` arguments. The arguments are provided as a variable number
322 of parameters followed by *NULL*.
323
324 Return the result of the call on success, or raise an exception and return
325 *NULL* on failure.
326
327
328 .. c:function:: PyObject* PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
329
330 Call a method of the Python object *obj* without arguments,
331 where the name of the method is given as a Python string object in *name*.
332
333 Return the result of the call on success, or raise an exception and return
334 *NULL* on failure.
335
336 .. versionadded:: 3.9
337
338
339 .. c:function:: PyObject* PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
340
341 Call a method of the Python object *obj* with a single positional argument
342 *arg*, where the name of the method is given as a Python string object in
343 *name*.
344
345 Return the result of the call on success, or raise an exception and return
346 *NULL* on failure.
347
348 .. versionadded:: 3.9
349
350 .. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
351 :no-typesetting:
352
353 .. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
354
355 Call a callable Python object *callable*.
356 The arguments are the same as for :c:type:`vectorcallfunc`.
357 If *callable* supports vectorcall_, this directly calls
358 the vectorcall function stored in *callable*.
359
360 Return the result of the call on success, or raise an exception and return
361 *NULL* on failure.
362
363 .. versionadded:: 3.8 as ``_PyObject_Vectorcall``
364
365 .. versionchanged:: 3.9
366
367 Renamed to the current name, without the leading underscore.
368 The old provisional name is :term:`soft deprecated`.
369
370 .. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
371
372 Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol,
373 but with keyword arguments passed as a dictionary *kwdict*.
374 The *args* array contains only the positional arguments.
375
376 Regardless of which protocol is used internally,
377 a conversion of arguments needs to be done.
378 Therefore, this function should only be used if the caller
379 already has a dictionary ready to use for the keyword arguments,
380 but not a tuple for the positional arguments.
381
382 .. versionadded:: 3.9
383
384 .. c:function:: PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
385
386 Call a method using the vectorcall calling convention. The name of the method
387 is given as a Python string *name*. The object whose method is called is
388 *args[0]*, and the *args* array starting at *args[1]* represents the arguments
389 of the call. There must be at least one positional argument.
390 *nargsf* is the number of positional arguments including *args[0]*,
391 plus :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
392 temporarily be changed. Keyword arguments can be passed just like in
393 :c:func:`PyObject_Vectorcall`.
394
395 If the object has the :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
396 this will call the unbound method object with the full
397 *args* vector as arguments.
398
399 Return the result of the call on success, or raise an exception and return
400 *NULL* on failure.
401
402 .. versionadded:: 3.9
403
404
405 Call Support API
406 ----------------
407
408 .. c:function:: int PyCallable_Check(PyObject *o)
409
410 Determine if the object *o* is callable. Return ``1`` if the object is callable
411 and ``0`` otherwise. This function always succeeds.