1.. highlight:: c 2 3.. _call: 4 5Call Protocol 6============= 7 8CPython supports two different calling protocols: 9*tp_call* and vectorcall. 10 11The *tp_call* Protocol 12---------------------- 13 14Instances of classes that set :c:member:`~PyTypeObject.tp_call` are callable. 15The signature of the slot is:: 16 17 PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs); 18 19A call is made using a tuple for the positional arguments 20and 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) 23but *kwargs* may be *NULL* if there are no keyword arguments. 24 25This convention is not only used by *tp_call*: 26:c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_init` 27also pass arguments this way. 28 29To call an object, use :c:func:`PyObject_Call` or another 30:ref:`call API <capi-call>`. 31 32 33.. _vectorcall: 34 35The Vectorcall Protocol 36----------------------- 37 38.. versionadded:: 3.9 39 40The vectorcall protocol was introduced in :pep:`590` as an additional protocol 41for making calls more efficient. 42 43As rule of thumb, CPython will prefer the vectorcall for internal calls 44if the callable supports it. However, this is not a hard rule. 45Additionally, some third-party extensions use *tp_call* directly 46(rather than using :c:func:`PyObject_Call`). 47Therefore, a class supporting vectorcall must also implement 48:c:member:`~PyTypeObject.tp_call`. 49Moreover, the callable must behave the same 50regardless of which protocol is used. 51The recommended way to achieve this is by setting 52:c:member:`~PyTypeObject.tp_call` to :c:func:`PyVectorcall_Call`. 53This 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 69A class should not implement vectorcall if that would be slower 70than *tp_call*. For example, if the callee needs to convert 71the arguments to an args tuple and kwargs dict anyway, then there is no point 72in implementing vectorcall. 73 74Classes 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 77object structure where a *vectorcallfunc* appears. 78This 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 113To call an object that implements vectorcall, use a :ref:`call API <capi-call>` 114function as with any other callable. 115:c:func:`PyObject_Vectorcall` will usually be most efficient. 116 117 118Recursion Control 119................. 120 121When 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` 124for calls made using *tp_call*. 125 126For efficiency, this is not the case for calls done using vectorcall: 127the callee should use *Py_EnterRecursiveCall* and *Py_LeaveRecursiveCall* 128if needed. 129 130 131Vectorcall 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 174Object Calling API 175------------------ 176 177Various functions are available for calling a Python object. 178Each converts its arguments to a convention supported by the called object – 179either *tp_call* or vectorcall. 180In order to do as little conversion as possible, pick one that best fits 181the format of data you have available. 182 183The following table summarizes the available functions; 184please 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 351.. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames) 352 353 Call a callable Python object *callable*. 354 The arguments are the same as for :c:type:`vectorcallfunc`. 355 If *callable* supports vectorcall_, this directly calls 356 the vectorcall function stored in *callable*. 357 358 Return the result of the call on success, or raise an exception and return 359 *NULL* on failure. 360 361 .. versionadded:: 3.9 362 363.. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict) 364 365 Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol, 366 but with keyword arguments passed as a dictionary *kwdict*. 367 The *args* array contains only the positional arguments. 368 369 Regardless of which protocol is used internally, 370 a conversion of arguments needs to be done. 371 Therefore, this function should only be used if the caller 372 already has a dictionary ready to use for the keyword arguments, 373 but not a tuple for the positional arguments. 374 375 .. versionadded:: 3.9 376 377.. c:function:: PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames) 378 379 Call a method using the vectorcall calling convention. The name of the method 380 is given as a Python string *name*. The object whose method is called is 381 *args[0]*, and the *args* array starting at *args[1]* represents the arguments 382 of the call. There must be at least one positional argument. 383 *nargsf* is the number of positional arguments including *args[0]*, 384 plus :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may 385 temporarily be changed. Keyword arguments can be passed just like in 386 :c:func:`PyObject_Vectorcall`. 387 388 If the object has the :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature, 389 this will call the unbound method object with the full 390 *args* vector as arguments. 391 392 Return the result of the call on success, or raise an exception and return 393 *NULL* on failure. 394 395 .. versionadded:: 3.9 396 397 398Call Support API 399---------------- 400 401.. c:function:: int PyCallable_Check(PyObject *o) 402 403 Determine if the object *o* is callable. Return ``1`` if the object is callable 404 and ``0`` otherwise. This function always succeeds. 405