17db96d56Sopenharmony_ci.. highlight:: c 27db96d56Sopenharmony_ci 37db96d56Sopenharmony_ci.. _call: 47db96d56Sopenharmony_ci 57db96d56Sopenharmony_ciCall Protocol 67db96d56Sopenharmony_ci============= 77db96d56Sopenharmony_ci 87db96d56Sopenharmony_ciCPython supports two different calling protocols: 97db96d56Sopenharmony_ci*tp_call* and vectorcall. 107db96d56Sopenharmony_ci 117db96d56Sopenharmony_ciThe *tp_call* Protocol 127db96d56Sopenharmony_ci---------------------- 137db96d56Sopenharmony_ci 147db96d56Sopenharmony_ciInstances of classes that set :c:member:`~PyTypeObject.tp_call` are callable. 157db96d56Sopenharmony_ciThe signature of the slot is:: 167db96d56Sopenharmony_ci 177db96d56Sopenharmony_ci PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs); 187db96d56Sopenharmony_ci 197db96d56Sopenharmony_ciA call is made using a tuple for the positional arguments 207db96d56Sopenharmony_ciand a dict for the keyword arguments, similarly to 217db96d56Sopenharmony_ci``callable(*args, **kwargs)`` in Python code. 227db96d56Sopenharmony_ci*args* must be non-NULL (use an empty tuple if there are no arguments) 237db96d56Sopenharmony_cibut *kwargs* may be *NULL* if there are no keyword arguments. 247db96d56Sopenharmony_ci 257db96d56Sopenharmony_ciThis convention is not only used by *tp_call*: 267db96d56Sopenharmony_ci:c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_init` 277db96d56Sopenharmony_cialso pass arguments this way. 287db96d56Sopenharmony_ci 297db96d56Sopenharmony_ciTo call an object, use :c:func:`PyObject_Call` or another 307db96d56Sopenharmony_ci:ref:`call API <capi-call>`. 317db96d56Sopenharmony_ci 327db96d56Sopenharmony_ci 337db96d56Sopenharmony_ci.. _vectorcall: 347db96d56Sopenharmony_ci 357db96d56Sopenharmony_ciThe Vectorcall Protocol 367db96d56Sopenharmony_ci----------------------- 377db96d56Sopenharmony_ci 387db96d56Sopenharmony_ci.. versionadded:: 3.9 397db96d56Sopenharmony_ci 407db96d56Sopenharmony_ciThe vectorcall protocol was introduced in :pep:`590` as an additional protocol 417db96d56Sopenharmony_cifor making calls more efficient. 427db96d56Sopenharmony_ci 437db96d56Sopenharmony_ciAs rule of thumb, CPython will prefer the vectorcall for internal calls 447db96d56Sopenharmony_ciif the callable supports it. However, this is not a hard rule. 457db96d56Sopenharmony_ciAdditionally, some third-party extensions use *tp_call* directly 467db96d56Sopenharmony_ci(rather than using :c:func:`PyObject_Call`). 477db96d56Sopenharmony_ciTherefore, a class supporting vectorcall must also implement 487db96d56Sopenharmony_ci:c:member:`~PyTypeObject.tp_call`. 497db96d56Sopenharmony_ciMoreover, the callable must behave the same 507db96d56Sopenharmony_ciregardless of which protocol is used. 517db96d56Sopenharmony_ciThe recommended way to achieve this is by setting 527db96d56Sopenharmony_ci:c:member:`~PyTypeObject.tp_call` to :c:func:`PyVectorcall_Call`. 537db96d56Sopenharmony_ciThis bears repeating: 547db96d56Sopenharmony_ci 557db96d56Sopenharmony_ci.. warning:: 567db96d56Sopenharmony_ci 577db96d56Sopenharmony_ci A class supporting vectorcall **must** also implement 587db96d56Sopenharmony_ci :c:member:`~PyTypeObject.tp_call` with the same semantics. 597db96d56Sopenharmony_ci 607db96d56Sopenharmony_ciA class should not implement vectorcall if that would be slower 617db96d56Sopenharmony_cithan *tp_call*. For example, if the callee needs to convert 627db96d56Sopenharmony_cithe arguments to an args tuple and kwargs dict anyway, then there is no point 637db96d56Sopenharmony_ciin implementing vectorcall. 647db96d56Sopenharmony_ci 657db96d56Sopenharmony_ciClasses can implement the vectorcall protocol by enabling the 667db96d56Sopenharmony_ci:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting 677db96d56Sopenharmony_ci:c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the 687db96d56Sopenharmony_ciobject structure where a *vectorcallfunc* appears. 697db96d56Sopenharmony_ciThis is a pointer to a function with the following signature: 707db96d56Sopenharmony_ci 717db96d56Sopenharmony_ci.. c:type:: PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames) 727db96d56Sopenharmony_ci 737db96d56Sopenharmony_ci- *callable* is the object being called. 747db96d56Sopenharmony_ci- *args* is a C array consisting of the positional arguments followed by the 757db96d56Sopenharmony_ci values of the keyword arguments. 767db96d56Sopenharmony_ci This can be *NULL* if there are no arguments. 777db96d56Sopenharmony_ci- *nargsf* is the number of positional arguments plus possibly the 787db96d56Sopenharmony_ci :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag. 797db96d56Sopenharmony_ci To get the actual number of positional arguments from *nargsf*, 807db96d56Sopenharmony_ci use :c:func:`PyVectorcall_NARGS`. 817db96d56Sopenharmony_ci- *kwnames* is a tuple containing the names of the keyword arguments; 827db96d56Sopenharmony_ci in other words, the keys of the kwargs dict. 837db96d56Sopenharmony_ci These names must be strings (instances of ``str`` or a subclass) 847db96d56Sopenharmony_ci and they must be unique. 857db96d56Sopenharmony_ci If there are no keyword arguments, then *kwnames* can instead be *NULL*. 867db96d56Sopenharmony_ci 877db96d56Sopenharmony_ci.. c:macro:: PY_VECTORCALL_ARGUMENTS_OFFSET 887db96d56Sopenharmony_ci 897db96d56Sopenharmony_ci If this flag is set in a vectorcall *nargsf* argument, the callee is allowed 907db96d56Sopenharmony_ci to temporarily change ``args[-1]``. In other words, *args* points to 917db96d56Sopenharmony_ci argument 1 (not 0) in the allocated vector. 927db96d56Sopenharmony_ci The callee must restore the value of ``args[-1]`` before returning. 937db96d56Sopenharmony_ci 947db96d56Sopenharmony_ci For :c:func:`PyObject_VectorcallMethod`, this flag means instead that 957db96d56Sopenharmony_ci ``args[0]`` may be changed. 967db96d56Sopenharmony_ci 977db96d56Sopenharmony_ci Whenever they can do so cheaply (without additional allocation), callers 987db96d56Sopenharmony_ci are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`. 997db96d56Sopenharmony_ci Doing so will allow callables such as bound methods to make their onward 1007db96d56Sopenharmony_ci calls (which include a prepended *self* argument) very efficiently. 1017db96d56Sopenharmony_ci 1027db96d56Sopenharmony_ciTo call an object that implements vectorcall, use a :ref:`call API <capi-call>` 1037db96d56Sopenharmony_cifunction as with any other callable. 1047db96d56Sopenharmony_ci:c:func:`PyObject_Vectorcall` will usually be most efficient. 1057db96d56Sopenharmony_ci 1067db96d56Sopenharmony_ci 1077db96d56Sopenharmony_ci.. note:: 1087db96d56Sopenharmony_ci 1097db96d56Sopenharmony_ci In CPython 3.8, the vectorcall API and related functions were available 1107db96d56Sopenharmony_ci provisionally under names with a leading underscore: 1117db96d56Sopenharmony_ci ``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``, 1127db96d56Sopenharmony_ci ``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``, 1137db96d56Sopenharmony_ci ``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``, 1147db96d56Sopenharmony_ci ``_PyObject_CallMethodOneArg``. 1157db96d56Sopenharmony_ci Additionally, ``PyObject_VectorcallDict`` was available as 1167db96d56Sopenharmony_ci ``_PyObject_FastCallDict``. 1177db96d56Sopenharmony_ci The old names are still defined as aliases of the new, non-underscored names. 1187db96d56Sopenharmony_ci 1197db96d56Sopenharmony_ci 1207db96d56Sopenharmony_ciRecursion Control 1217db96d56Sopenharmony_ci................. 1227db96d56Sopenharmony_ci 1237db96d56Sopenharmony_ciWhen using *tp_call*, callees do not need to worry about 1247db96d56Sopenharmony_ci:ref:`recursion <recursion>`: CPython uses 1257db96d56Sopenharmony_ci:c:func:`Py_EnterRecursiveCall` and :c:func:`Py_LeaveRecursiveCall` 1267db96d56Sopenharmony_cifor calls made using *tp_call*. 1277db96d56Sopenharmony_ci 1287db96d56Sopenharmony_ciFor efficiency, this is not the case for calls done using vectorcall: 1297db96d56Sopenharmony_cithe callee should use *Py_EnterRecursiveCall* and *Py_LeaveRecursiveCall* 1307db96d56Sopenharmony_ciif needed. 1317db96d56Sopenharmony_ci 1327db96d56Sopenharmony_ci 1337db96d56Sopenharmony_ciVectorcall Support API 1347db96d56Sopenharmony_ci...................... 1357db96d56Sopenharmony_ci 1367db96d56Sopenharmony_ci.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf) 1377db96d56Sopenharmony_ci 1387db96d56Sopenharmony_ci Given a vectorcall *nargsf* argument, return the actual number of 1397db96d56Sopenharmony_ci arguments. 1407db96d56Sopenharmony_ci Currently equivalent to:: 1417db96d56Sopenharmony_ci 1427db96d56Sopenharmony_ci (Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET) 1437db96d56Sopenharmony_ci 1447db96d56Sopenharmony_ci However, the function ``PyVectorcall_NARGS`` should be used to allow 1457db96d56Sopenharmony_ci for future extensions. 1467db96d56Sopenharmony_ci 1477db96d56Sopenharmony_ci .. versionadded:: 3.8 1487db96d56Sopenharmony_ci 1497db96d56Sopenharmony_ci.. c:function:: vectorcallfunc PyVectorcall_Function(PyObject *op) 1507db96d56Sopenharmony_ci 1517db96d56Sopenharmony_ci If *op* does not support the vectorcall protocol (either because the type 1527db96d56Sopenharmony_ci does not or because the specific instance does not), return *NULL*. 1537db96d56Sopenharmony_ci Otherwise, return the vectorcall function pointer stored in *op*. 1547db96d56Sopenharmony_ci This function never raises an exception. 1557db96d56Sopenharmony_ci 1567db96d56Sopenharmony_ci This is mostly useful to check whether or not *op* supports vectorcall, 1577db96d56Sopenharmony_ci which can be done by checking ``PyVectorcall_Function(op) != NULL``. 1587db96d56Sopenharmony_ci 1597db96d56Sopenharmony_ci .. versionadded:: 3.8 1607db96d56Sopenharmony_ci 1617db96d56Sopenharmony_ci.. c:function:: PyObject* PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict) 1627db96d56Sopenharmony_ci 1637db96d56Sopenharmony_ci Call *callable*'s :c:type:`vectorcallfunc` with positional and keyword 1647db96d56Sopenharmony_ci arguments given in a tuple and dict, respectively. 1657db96d56Sopenharmony_ci 1667db96d56Sopenharmony_ci This is a specialized function, intended to be put in the 1677db96d56Sopenharmony_ci :c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``. 1687db96d56Sopenharmony_ci It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag 1697db96d56Sopenharmony_ci and it does not fall back to ``tp_call``. 1707db96d56Sopenharmony_ci 1717db96d56Sopenharmony_ci .. versionadded:: 3.8 1727db96d56Sopenharmony_ci 1737db96d56Sopenharmony_ci 1747db96d56Sopenharmony_ci.. _capi-call: 1757db96d56Sopenharmony_ci 1767db96d56Sopenharmony_ciObject Calling API 1777db96d56Sopenharmony_ci------------------ 1787db96d56Sopenharmony_ci 1797db96d56Sopenharmony_ciVarious functions are available for calling a Python object. 1807db96d56Sopenharmony_ciEach converts its arguments to a convention supported by the called object – 1817db96d56Sopenharmony_cieither *tp_call* or vectorcall. 1827db96d56Sopenharmony_ciIn order to do as little conversion as possible, pick one that best fits 1837db96d56Sopenharmony_cithe format of data you have available. 1847db96d56Sopenharmony_ci 1857db96d56Sopenharmony_ciThe following table summarizes the available functions; 1867db96d56Sopenharmony_ciplease see individual documentation for details. 1877db96d56Sopenharmony_ci 1887db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 1897db96d56Sopenharmony_ci| Function | callable | args | kwargs | 1907db96d56Sopenharmony_ci+==========================================+==================+====================+===============+ 1917db96d56Sopenharmony_ci| :c:func:`PyObject_Call` | ``PyObject *`` | tuple | dict/``NULL`` | 1927db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 1937db96d56Sopenharmony_ci| :c:func:`PyObject_CallNoArgs` | ``PyObject *`` | --- | --- | 1947db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 1957db96d56Sopenharmony_ci| :c:func:`PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- | 1967db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 1977db96d56Sopenharmony_ci| :c:func:`PyObject_CallObject` | ``PyObject *`` | tuple/``NULL`` | --- | 1987db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 1997db96d56Sopenharmony_ci| :c:func:`PyObject_CallFunction` | ``PyObject *`` | format | --- | 2007db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 2017db96d56Sopenharmony_ci| :c:func:`PyObject_CallMethod` | obj + ``char*`` | format | --- | 2027db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 2037db96d56Sopenharmony_ci| :c:func:`PyObject_CallFunctionObjArgs` | ``PyObject *`` | variadic | --- | 2047db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 2057db96d56Sopenharmony_ci| :c:func:`PyObject_CallMethodObjArgs` | obj + name | variadic | --- | 2067db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 2077db96d56Sopenharmony_ci| :c:func:`PyObject_CallMethodNoArgs` | obj + name | --- | --- | 2087db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 2097db96d56Sopenharmony_ci| :c:func:`PyObject_CallMethodOneArg` | obj + name | 1 object | --- | 2107db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 2117db96d56Sopenharmony_ci| :c:func:`PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall | 2127db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 2137db96d56Sopenharmony_ci| :c:func:`PyObject_VectorcallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` | 2147db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 2157db96d56Sopenharmony_ci| :c:func:`PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall | 2167db96d56Sopenharmony_ci+------------------------------------------+------------------+--------------------+---------------+ 2177db96d56Sopenharmony_ci 2187db96d56Sopenharmony_ci 2197db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs) 2207db96d56Sopenharmony_ci 2217db96d56Sopenharmony_ci Call a callable Python object *callable*, with arguments given by the 2227db96d56Sopenharmony_ci tuple *args*, and named arguments given by the dictionary *kwargs*. 2237db96d56Sopenharmony_ci 2247db96d56Sopenharmony_ci *args* must not be *NULL*; use an empty tuple if no arguments are needed. 2257db96d56Sopenharmony_ci If no named arguments are needed, *kwargs* can be *NULL*. 2267db96d56Sopenharmony_ci 2277db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 2287db96d56Sopenharmony_ci *NULL* on failure. 2297db96d56Sopenharmony_ci 2307db96d56Sopenharmony_ci This is the equivalent of the Python expression: 2317db96d56Sopenharmony_ci ``callable(*args, **kwargs)``. 2327db96d56Sopenharmony_ci 2337db96d56Sopenharmony_ci 2347db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_CallNoArgs(PyObject *callable) 2357db96d56Sopenharmony_ci 2367db96d56Sopenharmony_ci Call a callable Python object *callable* without any arguments. It is the 2377db96d56Sopenharmony_ci most efficient way to call a callable Python object without any argument. 2387db96d56Sopenharmony_ci 2397db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 2407db96d56Sopenharmony_ci *NULL* on failure. 2417db96d56Sopenharmony_ci 2427db96d56Sopenharmony_ci .. versionadded:: 3.9 2437db96d56Sopenharmony_ci 2447db96d56Sopenharmony_ci 2457db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_CallOneArg(PyObject *callable, PyObject *arg) 2467db96d56Sopenharmony_ci 2477db96d56Sopenharmony_ci Call a callable Python object *callable* with exactly 1 positional argument 2487db96d56Sopenharmony_ci *arg* and no keyword arguments. 2497db96d56Sopenharmony_ci 2507db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 2517db96d56Sopenharmony_ci *NULL* on failure. 2527db96d56Sopenharmony_ci 2537db96d56Sopenharmony_ci .. versionadded:: 3.9 2547db96d56Sopenharmony_ci 2557db96d56Sopenharmony_ci 2567db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args) 2577db96d56Sopenharmony_ci 2587db96d56Sopenharmony_ci Call a callable Python object *callable*, with arguments given by the 2597db96d56Sopenharmony_ci tuple *args*. If no arguments are needed, then *args* can be *NULL*. 2607db96d56Sopenharmony_ci 2617db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 2627db96d56Sopenharmony_ci *NULL* on failure. 2637db96d56Sopenharmony_ci 2647db96d56Sopenharmony_ci This is the equivalent of the Python expression: ``callable(*args)``. 2657db96d56Sopenharmony_ci 2667db96d56Sopenharmony_ci 2677db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...) 2687db96d56Sopenharmony_ci 2697db96d56Sopenharmony_ci Call a callable Python object *callable*, with a variable number of C arguments. 2707db96d56Sopenharmony_ci The C arguments are described using a :c:func:`Py_BuildValue` style format 2717db96d56Sopenharmony_ci string. The format can be *NULL*, indicating that no arguments are provided. 2727db96d56Sopenharmony_ci 2737db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 2747db96d56Sopenharmony_ci *NULL* on failure. 2757db96d56Sopenharmony_ci 2767db96d56Sopenharmony_ci This is the equivalent of the Python expression: ``callable(*args)``. 2777db96d56Sopenharmony_ci 2787db96d56Sopenharmony_ci Note that if you only pass :c:expr:`PyObject *` args, 2797db96d56Sopenharmony_ci :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative. 2807db96d56Sopenharmony_ci 2817db96d56Sopenharmony_ci .. versionchanged:: 3.4 2827db96d56Sopenharmony_ci The type of *format* was changed from ``char *``. 2837db96d56Sopenharmony_ci 2847db96d56Sopenharmony_ci 2857db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...) 2867db96d56Sopenharmony_ci 2877db96d56Sopenharmony_ci Call the method named *name* of object *obj* with a variable number of C 2887db96d56Sopenharmony_ci arguments. The C arguments are described by a :c:func:`Py_BuildValue` format 2897db96d56Sopenharmony_ci string that should produce a tuple. 2907db96d56Sopenharmony_ci 2917db96d56Sopenharmony_ci The format can be *NULL*, indicating that no arguments are provided. 2927db96d56Sopenharmony_ci 2937db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 2947db96d56Sopenharmony_ci *NULL* on failure. 2957db96d56Sopenharmony_ci 2967db96d56Sopenharmony_ci This is the equivalent of the Python expression: 2977db96d56Sopenharmony_ci ``obj.name(arg1, arg2, ...)``. 2987db96d56Sopenharmony_ci 2997db96d56Sopenharmony_ci Note that if you only pass :c:expr:`PyObject *` args, 3007db96d56Sopenharmony_ci :c:func:`PyObject_CallMethodObjArgs` is a faster alternative. 3017db96d56Sopenharmony_ci 3027db96d56Sopenharmony_ci .. versionchanged:: 3.4 3037db96d56Sopenharmony_ci The types of *name* and *format* were changed from ``char *``. 3047db96d56Sopenharmony_ci 3057db96d56Sopenharmony_ci 3067db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...) 3077db96d56Sopenharmony_ci 3087db96d56Sopenharmony_ci Call a callable Python object *callable*, with a variable number of 3097db96d56Sopenharmony_ci :c:expr:`PyObject *` arguments. The arguments are provided as a variable number 3107db96d56Sopenharmony_ci of parameters followed by *NULL*. 3117db96d56Sopenharmony_ci 3127db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 3137db96d56Sopenharmony_ci *NULL* on failure. 3147db96d56Sopenharmony_ci 3157db96d56Sopenharmony_ci This is the equivalent of the Python expression: 3167db96d56Sopenharmony_ci ``callable(arg1, arg2, ...)``. 3177db96d56Sopenharmony_ci 3187db96d56Sopenharmony_ci 3197db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...) 3207db96d56Sopenharmony_ci 3217db96d56Sopenharmony_ci Call a method of the Python object *obj*, where the name of the method is given as a 3227db96d56Sopenharmony_ci Python string object in *name*. It is called with a variable number of 3237db96d56Sopenharmony_ci :c:expr:`PyObject *` arguments. The arguments are provided as a variable number 3247db96d56Sopenharmony_ci of parameters followed by *NULL*. 3257db96d56Sopenharmony_ci 3267db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 3277db96d56Sopenharmony_ci *NULL* on failure. 3287db96d56Sopenharmony_ci 3297db96d56Sopenharmony_ci 3307db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name) 3317db96d56Sopenharmony_ci 3327db96d56Sopenharmony_ci Call a method of the Python object *obj* without arguments, 3337db96d56Sopenharmony_ci where the name of the method is given as a Python string object in *name*. 3347db96d56Sopenharmony_ci 3357db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 3367db96d56Sopenharmony_ci *NULL* on failure. 3377db96d56Sopenharmony_ci 3387db96d56Sopenharmony_ci .. versionadded:: 3.9 3397db96d56Sopenharmony_ci 3407db96d56Sopenharmony_ci 3417db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg) 3427db96d56Sopenharmony_ci 3437db96d56Sopenharmony_ci Call a method of the Python object *obj* with a single positional argument 3447db96d56Sopenharmony_ci *arg*, where the name of the method is given as a Python string object in 3457db96d56Sopenharmony_ci *name*. 3467db96d56Sopenharmony_ci 3477db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 3487db96d56Sopenharmony_ci *NULL* on failure. 3497db96d56Sopenharmony_ci 3507db96d56Sopenharmony_ci .. versionadded:: 3.9 3517db96d56Sopenharmony_ci 3527db96d56Sopenharmony_ci 3537db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames) 3547db96d56Sopenharmony_ci 3557db96d56Sopenharmony_ci Call a callable Python object *callable*. 3567db96d56Sopenharmony_ci The arguments are the same as for :c:type:`vectorcallfunc`. 3577db96d56Sopenharmony_ci If *callable* supports vectorcall_, this directly calls 3587db96d56Sopenharmony_ci the vectorcall function stored in *callable*. 3597db96d56Sopenharmony_ci 3607db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 3617db96d56Sopenharmony_ci *NULL* on failure. 3627db96d56Sopenharmony_ci 3637db96d56Sopenharmony_ci .. versionadded:: 3.9 3647db96d56Sopenharmony_ci 3657db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict) 3667db96d56Sopenharmony_ci 3677db96d56Sopenharmony_ci Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol, 3687db96d56Sopenharmony_ci but with keyword arguments passed as a dictionary *kwdict*. 3697db96d56Sopenharmony_ci The *args* array contains only the positional arguments. 3707db96d56Sopenharmony_ci 3717db96d56Sopenharmony_ci Regardless of which protocol is used internally, 3727db96d56Sopenharmony_ci a conversion of arguments needs to be done. 3737db96d56Sopenharmony_ci Therefore, this function should only be used if the caller 3747db96d56Sopenharmony_ci already has a dictionary ready to use for the keyword arguments, 3757db96d56Sopenharmony_ci but not a tuple for the positional arguments. 3767db96d56Sopenharmony_ci 3777db96d56Sopenharmony_ci .. versionadded:: 3.9 3787db96d56Sopenharmony_ci 3797db96d56Sopenharmony_ci.. c:function:: PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames) 3807db96d56Sopenharmony_ci 3817db96d56Sopenharmony_ci Call a method using the vectorcall calling convention. The name of the method 3827db96d56Sopenharmony_ci is given as a Python string *name*. The object whose method is called is 3837db96d56Sopenharmony_ci *args[0]*, and the *args* array starting at *args[1]* represents the arguments 3847db96d56Sopenharmony_ci of the call. There must be at least one positional argument. 3857db96d56Sopenharmony_ci *nargsf* is the number of positional arguments including *args[0]*, 3867db96d56Sopenharmony_ci plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may 3877db96d56Sopenharmony_ci temporarily be changed. Keyword arguments can be passed just like in 3887db96d56Sopenharmony_ci :c:func:`PyObject_Vectorcall`. 3897db96d56Sopenharmony_ci 3907db96d56Sopenharmony_ci If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature, 3917db96d56Sopenharmony_ci this will call the unbound method object with the full 3927db96d56Sopenharmony_ci *args* vector as arguments. 3937db96d56Sopenharmony_ci 3947db96d56Sopenharmony_ci Return the result of the call on success, or raise an exception and return 3957db96d56Sopenharmony_ci *NULL* on failure. 3967db96d56Sopenharmony_ci 3977db96d56Sopenharmony_ci .. versionadded:: 3.9 3987db96d56Sopenharmony_ci 3997db96d56Sopenharmony_ci 4007db96d56Sopenharmony_ciCall Support API 4017db96d56Sopenharmony_ci---------------- 4027db96d56Sopenharmony_ci 4037db96d56Sopenharmony_ci.. c:function:: int PyCallable_Check(PyObject *o) 4047db96d56Sopenharmony_ci 4057db96d56Sopenharmony_ci Determine if the object *o* is callable. Return ``1`` if the object is callable 4067db96d56Sopenharmony_ci and ``0`` otherwise. This function always succeeds. 407