Doc/c-api/call.rst

.. highlight:: c

.. _call:

Call Protocol
=============

CPython supports two different calling protocols:
*tp_call* and vectorcall.

The *tp_call* Protocol
----------------------

Instances of classes that set :c:member:`~PyTypeObject.tp_call` are callable.
The signature of the slot is::

    PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);

A call is made using a tuple for the positional arguments
and a dict for the keyword arguments, similarly to
``callable(*args, **kwargs)`` in Python code.
*args* must be non-NULL (use an empty tuple if there are no arguments)
but *kwargs* may be *NULL* if there are no keyword arguments.

This convention is not only used by *tp_call*:
:c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_init`
also pass arguments this way.

To call an object, use :c:func:`PyObject_Call` or another
:ref:`call API <capi-call>`.


.. _vectorcall:

The Vectorcall Protocol
-----------------------

.. versionadded:: 3.9

The vectorcall protocol was introduced in :pep:`590` as an additional protocol
for making calls more efficient.

As rule of thumb, CPython will prefer the vectorcall for internal calls
if the callable supports it. However, this is not a hard rule.
Additionally, some third-party extensions use *tp_call* directly
(rather than using :c:func:`PyObject_Call`).
Therefore, a class supporting vectorcall must also implement
:c:member:`~PyTypeObject.tp_call`.
Moreover, the callable must behave the same
regardless of which protocol is used.
The recommended way to achieve this is by setting
:c:member:`~PyTypeObject.tp_call` to :c:func:`PyVectorcall_Call`.
This bears repeating:

.. warning::

   A class supporting vectorcall **must** also implement
   :c:member:`~PyTypeObject.tp_call` with the same semantics.

A class should not implement vectorcall if that would be slower
than *tp_call*. For example, if the callee needs to convert
the arguments to an args tuple and kwargs dict anyway, then there is no point
in implementing vectorcall.

Classes can implement the vectorcall protocol by enabling the
:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
:c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the
object structure where a *vectorcallfunc* appears.
This is a pointer to a function with the following signature:

.. c:type:: PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

- *callable* is the object being called.
- *args* is a C array consisting of the positional arguments followed by the
   values of the keyword arguments.
   This can be *NULL* if there are no arguments.
- *nargsf* is the number of positional arguments plus possibly the
   :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
   To get the actual number of positional arguments from *nargsf*,
   use :c:func:`PyVectorcall_NARGS`.
- *kwnames* is a tuple containing the names of the keyword arguments;
   in other words, the keys of the kwargs dict.
   These names must be strings (instances of ``str`` or a subclass)
   and they must be unique.
   If there are no keyword arguments, then *kwnames* can instead be *NULL*.

.. c:macro:: PY_VECTORCALL_ARGUMENTS_OFFSET

   If this flag is set in a vectorcall *nargsf* argument, the callee is allowed
   to temporarily change ``args[-1]``. In other words, *args* points to
   argument 1 (not 0) in the allocated vector.
   The callee must restore the value of ``args[-1]`` before returning.

   For :c:func:`PyObject_VectorcallMethod`, this flag means instead that
   ``args[0]`` may be changed.

   Whenever they can do so cheaply (without additional allocation), callers
   are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
   Doing so will allow callables such as bound methods to make their onward
   calls (which include a prepended *self* argument) very efficiently.

To call an object that implements vectorcall, use a :ref:`call API <capi-call>`
function as with any other callable.
:c:func:`PyObject_Vectorcall` will usually be most efficient.


.. note::

   In CPython 3.8, the vectorcall API and related functions were available
   provisionally under names with a leading underscore:
   ``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``,
   ``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``,
   ``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``,
   ``_PyObject_CallMethodOneArg``.
   Additionally, ``PyObject_VectorcallDict`` was available as
   ``_PyObject_FastCallDict``.
   The old names are still defined as aliases of the new, non-underscored names.


Recursion Control
.................

When using *tp_call*, callees do not need to worry about
:ref:`recursion <recursion>`: CPython uses
:c:func:`Py_EnterRecursiveCall` and :c:func:`Py_LeaveRecursiveCall`
for calls made using *tp_call*.

For efficiency, this is not the case for calls done using vectorcall:
the callee should use *Py_EnterRecursiveCall* and *Py_LeaveRecursiveCall*
if needed.


Vectorcall Support API
......................

.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

   Given a vectorcall *nargsf* argument, return the actual number of
   arguments.
   Currently equivalent to::

      (Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)

   However, the function ``PyVectorcall_NARGS`` should be used to allow
   for future extensions.

   .. versionadded:: 3.8

.. c:function:: vectorcallfunc PyVectorcall_Function(PyObject *op)

   If *op* does not support the vectorcall protocol (either because the type
   does not or because the specific instance does not), return *NULL*.
   Otherwise, return the vectorcall function pointer stored in *op*.
   This function never raises an exception.

   This is mostly useful to check whether or not *op* supports vectorcall,
   which can be done by checking ``PyVectorcall_Function(op) != NULL``.

   .. versionadded:: 3.8

.. c:function:: PyObject* PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)

   Call *callable*'s :c:type:`vectorcallfunc` with positional and keyword
   arguments given in a tuple and dict, respectively.

   This is a specialized function, intended to be put in the
   :c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
   It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
   and it does not fall back to ``tp_call``.

   .. versionadded:: 3.8


.. _capi-call:

Object Calling API
------------------

Various functions are available for calling a Python object.
Each converts its arguments to a convention supported by the called object –
either *tp_call* or vectorcall.
In order to do as little conversion as possible, pick one that best fits
the format of data you have available.

The following table summarizes the available functions;
please see individual documentation for details.

+------------------------------------------+------------------+--------------------+---------------+
| Function                                 | callable         | args               | kwargs        |
+==========================================+==================+====================+===============+
| :c:func:`PyObject_Call`                  | ``PyObject *``   | tuple              | dict/``NULL`` |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallNoArgs`            | ``PyObject *``   | ---                | ---           |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallOneArg`            | ``PyObject *``   | 1 object           | ---           |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallObject`            | ``PyObject *``   | tuple/``NULL``     | ---           |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallFunction`          | ``PyObject *``   | format             | ---           |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethod`            | obj + ``char*``  | format             | ---           |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallFunctionObjArgs`   | ``PyObject *``   | variadic           | ---           |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethodObjArgs`     | obj + name       | variadic           | ---           |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethodNoArgs`      | obj + name       | ---                | ---           |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethodOneArg`      | obj + name       | 1 object           | ---           |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_Vectorcall`            | ``PyObject *``   | vectorcall         | vectorcall    |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_VectorcallDict`        | ``PyObject *``   | vectorcall         | dict/``NULL`` |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_VectorcallMethod`      | arg + name       | vectorcall         | vectorcall    |
+------------------------------------------+------------------+--------------------+---------------+


.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)

   Call a callable Python object *callable*, with arguments given by the
   tuple *args*, and named arguments given by the dictionary *kwargs*.

   *args* must not be *NULL*; use an empty tuple if no arguments are needed.
   If no named arguments are needed, *kwargs* can be *NULL*.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   This is the equivalent of the Python expression:
   ``callable(*args, **kwargs)``.


.. c:function:: PyObject* PyObject_CallNoArgs(PyObject *callable)

   Call a callable Python object *callable* without any arguments. It is the
   most efficient way to call a callable Python object without any argument.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   .. versionadded:: 3.9


.. c:function:: PyObject* PyObject_CallOneArg(PyObject *callable, PyObject *arg)

   Call a callable Python object *callable* with exactly 1 positional argument
   *arg* and no keyword arguments.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   .. versionadded:: 3.9


.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)

   Call a callable Python object *callable*, with arguments given by the
   tuple *args*.  If no arguments are needed, then *args* can be *NULL*.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   This is the equivalent of the Python expression: ``callable(*args)``.


.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)

   Call a callable Python object *callable*, with a variable number of C arguments.
   The C arguments are described using a :c:func:`Py_BuildValue` style format
   string.  The format can be *NULL*, indicating that no arguments are provided.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   This is the equivalent of the Python expression: ``callable(*args)``.

   Note that if you only pass :c:expr:`PyObject *` args,
   :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.

   .. versionchanged:: 3.4
      The type of *format* was changed from ``char *``.


.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)

   Call the method named *name* of object *obj* with a variable number of C
   arguments.  The C arguments are described by a :c:func:`Py_BuildValue` format
   string that should produce a tuple.

   The format can be *NULL*, indicating that no arguments are provided.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   This is the equivalent of the Python expression:
   ``obj.name(arg1, arg2, ...)``.

   Note that if you only pass :c:expr:`PyObject *` args,
   :c:func:`PyObject_CallMethodObjArgs` is a faster alternative.

   .. versionchanged:: 3.4
      The types of *name* and *format* were changed from ``char *``.


.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...)

   Call a callable Python object *callable*, with a variable number of
   :c:expr:`PyObject *` arguments.  The arguments are provided as a variable number
   of parameters followed by *NULL*.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   This is the equivalent of the Python expression:
   ``callable(arg1, arg2, ...)``.


.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)

   Call a method of the Python object *obj*, where the name of the method is given as a
   Python string object in *name*.  It is called with a variable number of
   :c:expr:`PyObject *` arguments.  The arguments are provided as a variable number
   of parameters followed by *NULL*.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.


.. c:function:: PyObject* PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)

   Call a method of the Python object *obj* without arguments,
   where the name of the method is given as a Python string object in *name*.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   .. versionadded:: 3.9


.. c:function:: PyObject* PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)

   Call a method of the Python object *obj* with a single positional argument
   *arg*, where the name of the method is given as a Python string object in
   *name*.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   .. versionadded:: 3.9


.. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

   Call a callable Python object *callable*.
   The arguments are the same as for :c:type:`vectorcallfunc`.
   If *callable* supports vectorcall_, this directly calls
   the vectorcall function stored in *callable*.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   .. versionadded:: 3.9

.. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

   Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol,
   but with keyword arguments passed as a dictionary *kwdict*.
   The *args* array contains only the positional arguments.

   Regardless of which protocol is used internally,
   a conversion of arguments needs to be done.
   Therefore, this function should only be used if the caller
   already has a dictionary ready to use for the keyword arguments,
   but not a tuple for the positional arguments.

   .. versionadded:: 3.9

.. c:function:: PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)

   Call a method using the vectorcall calling convention. The name of the method
   is given as a Python string *name*. The object whose method is called is
   *args[0]*, and the *args* array starting at *args[1]* represents the arguments
   of the call. There must be at least one positional argument.
   *nargsf* is the number of positional arguments including *args[0]*,
   plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
   temporarily be changed. Keyword arguments can be passed just like in
   :c:func:`PyObject_Vectorcall`.

   If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
   this will call the unbound method object with the full
   *args* vector as arguments.

   Return the result of the call on success, or raise an exception and return
   *NULL* on failure.

   .. versionadded:: 3.9


Call Support API
----------------

.. c:function:: int PyCallable_Check(PyObject *o)

   Determine if the object *o* is callable.  Return ``1`` if the object is callable
   and ``0`` otherwise.  This function always succeeds.