调用协议

CPython 支持两种不同的调用协议：tp_call 和矢量调用。

tp_call 协议

设置 tp_call 的类的实例都是可调用的。 槽位的签名为:

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

一个调用是用一个元组表示位置参数，用一个dict表示关键字参数，类似于Python代码中的``callable(args, **kwargs)``。*args*必须是非空的（如果没有参数，会使用一个空元组），但如果没有关键字参数，*kwargs*可以是*NULL。

这个约定不仅被*tp_call*使用： tp_new 和 tp_init 也这样传递参数。

要调用一个对象，请使用 PyObject_Call() 或者其他的 调用 API。

Vectorcall 协议

3.9 新版功能.

vectorcall 协议是在 PEP 590 被引入的，它是使调用函数更加有效的附加协议。

作为经验法则，如果可调用程序支持 vectorcall，CPython 会更倾向于内联调用。 然而，这并不是一个硬性规定。 此外，一些第三方扩展直接使用 tp_call (而不是使用 PyObject_Call())。 因此，一个支持 vectorcall 的类也必须实现 tp_call。 此外，无论使用哪种协议，可调对象的行为都必须是相同的。 推荐的方法是将 tp_call 设置为 PyVectorcall_Call()。值得一提的是:

警告

一个支持 Vectorcall 的类 必须 也实现具有相同语义的 tp_call。

如果一个类的vectorcall比*tp_call*慢，就不应该实现vectorcall。例如，如果被调用者需要将参数转换为args 元组和kwargs dict，那么实现vectorcall就没有意义。

Classes can implement the vectorcall protocol by enabling the Py_TPFLAGS_HAVE_VECTORCALL flag and setting 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:

typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

• callable 是指被调用的对象。

• args 是一个C语言数组，由位置参数和后面的

  关键字参数的值。如果没有参数，这个值可以是 NULL 。

• nargsf 是位置参数的数量加上可能的

  PY_VECTORCALL_ARGUMENTS_OFFSET flag. To get the actual number of positional arguments from nargsf, use PyVectorcall_NARGS().

• kwnames 是一包含所有关键字名称的元组。

  换句话说，就是 kwargs 字典的键。 这些名字必须是字符串 (str 或其子类的实例)，并且它们必须是唯一的。 如果没有关键字参数，那么 kwnames 可以用 NULL 代替。

PY_VECTORCALL_ARGUMENTS_OFFSET

如果在 vectorcall 的 nargsf 参数中设置了此标志，则允许被调用者临时更改 args[-1] 的值。换句话说， args 指向分配向量中的参数 1（不是 0 ）。被调用方必须在返回之前还原 args[-1] 的值。

对于 PyObject_VectorcallMethod() ，这个标志的改变意味着``args[0]`` 可能改变了。

Whenever they can do so cheaply (without additional allocation), callers are encouraged to use 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.

要调用一个实现了 vectorcall 的对象，请使用某个 call API 函数，就像其他可调对象一样。 PyObject_Vectorcall() 通常是最有效的。

备注

在 CPython 3.8 中，vectorcall API 和相关的函数暂定以带开头下划线的名称提供: _PyObject_Vectorcall, _Py_TPFLAGS_HAVE_VECTORCALL, _PyObject_VectorcallMethod, _PyVectorcall_Function, _PyObject_CallOneArg, _PyObject_CallMethodNoArgs, _PyObject_CallMethodOneArg。 此外， PyObject_VectorcallDict 以 _PyObject_FastCallDict 的名称提供。 旧名称仍然被定义为不带下划线的新名称的别名。

递归控制

在使用 tp_call 时，被调用者不必担心 递归: CPython 对于使用 tp_call 进行的调用会使用 Py_EnterRecursiveCall() 和 Py_LeaveRecursiveCall()。

为保证效率，这不适用于使用 vectorcall 的调用：被调用方在需要时应当使用 Py_EnterRecursiveCall 和 Py_LeaveRecursiveCall。

Vectorcall 支持 API

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

给定一个 vectorcall nargsf 实参，返回参数的实际数量。 目前等同于:

(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)

然而，应使用 PyVectorcall_NARGS 函数以便将来扩展。

3.8 新版功能.

vectorcallfunc PyVectorcall_Function(PyObject *op)

如果*op*不支持vectorcall协议（要么是因为类型不支持，要么是因为具体实例不支持），返回*NULL*。否则，返回存储在*op*中的vectorcall函数指针。这个函数从不触发异常。

这在检查 op 是否支持 vectorcall 时最有用处，可以通过检查 PyVectorcall_Function(op) != NULL 来实现。

3.9 新版功能.

PyObject *PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)

调用*可调对象*的 vectorcallfunc，其位置参数和关键字参数分别以元组和dict形式给出。

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

3.8 新版功能.

调用对象的 API

有多个函数可被用来调用 Python 对象。 各个函数会将其参数转换为被调用对象所支持的惯例 – 可以是 tp_call 或 vectorcall。 为了尽可能少地进行转换，请选择一个适合你所拥有的数据格式的函数。

下表总结了可用的功能； 请参阅各个文档以了解详细信息。

函数	可调用对象（Callable）	args	kwargs
PyObject_Call()	PyObject *	元组	dict/NULL
PyObject_CallNoArgs()	PyObject *	---	---
PyObject_CallOneArg()	PyObject *	1个对象	---
PyObject_CallObject()	PyObject *	元组/NULL	---
PyObject_CallFunction()	PyObject *	format	---
PyObject_CallMethod()	对象 + char*	format	---
PyObject_CallFunctionObjArgs()	PyObject *	可变参数	---
PyObject_CallMethodObjArgs()	对象 + 名称	可变参数	---
PyObject_CallMethodNoArgs()	对象 + 名称	---	---
PyObject_CallMethodOneArg()	对象 + 名称	1个对象	---
PyObject_Vectorcall()	PyObject *	vectorcall	vectorcall
PyObject_VectorcallDict()	PyObject *	vectorcall	dict/NULL
PyObject_VectorcallMethod()	参数 + 名称	vectorcall	vectorcall

PyObject *PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)

返回值：新的引用。 Part of the Stable ABI.

调用一个可调用的 Python 对象 callable，附带由元组 args 所给出的参数，以及由字典 kwargs 所给出的关键字参数。

args 必须不为 NULL；如果不想要参数请使用一个空元组。 如果不想要关键字参数，则 kwargs 可以为 NULL。

成功时返回结果，在失败时抛出一个异常并返回 NULL。

这等价于 Python 表达式 callable(*args, **kwargs)。

PyObject *PyObject_CallNoArgs(PyObject *callable)

Part of the Stable ABI since version 3.10.

调用一个可调用的 Python 对象 callable 并不附带任何参数。 这是不带参数调用 Python 可调用对象的最有效方式。

成功时返回结果，在失败时抛出一个异常并返回 NULL。

3.9 新版功能.

PyObject *PyObject_CallOneArg(PyObject *callable, PyObject *arg)

调用一个可调用的 Python 对象 callable 并附带恰好 1 个位置参数 arg 而没有关键字参数。

成功时返回结果，在失败时抛出一个异常并返回 NULL。

3.9 新版功能.

PyObject *PyObject_CallObject(PyObject *callable, PyObject *args)

返回值：新的引用。 Part of the Stable ABI.

调用一个可调用的 Python 对象 callable，附带由元组 args 所给出的参数。 如果不想要传入参数，则 args 可以为 NULL。

成功时返回结果，在失败时抛出一个异常并返回 NULL。

这等价于 Python 表达式 callable(*args)。

PyObject *PyObject_CallFunction(PyObject *callable, const char *format, ...)

返回值：新的引用。 Part of the Stable ABI.

调用一个可调用的 Python 对象 callable，附带可变数量的 C 参数。 这些 C 参数使用 Py_BuildValue() 风格的格式字符串来描述。 format 可以为 NULL，表示没有提供任何参数。

成功时返回结果，在失败时抛出一个异常并返回 NULL。

这等价于 Python 表达式 callable(*args)。

Note that if you only pass PyObject* args, PyObject_CallFunctionObjArgs() is a faster alternative.

在 3.4 版更改: 这个 format 类型已从 char * 更改。

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

返回值：新的引用。 Part of the Stable ABI.

调用 obj 对象中名为 name 的方法并附带可变数量的 C 参数。 这些 C 参数由 Py_BuildValue() 格式字符串来描述并应当生成一个元组。

格式可以为 NULL ，表示未提供任何参数。

成功时返回结果，在失败时抛出一个异常并返回 NULL。

这和Python表达式``obj.name(arg1, arg2, ...)``是一样的。

Note that if you only pass PyObject* args, PyObject_CallMethodObjArgs() is a faster alternative.

在 3.4 版更改: The types of name and format were changed from char *.

PyObject *PyObject_CallFunctionObjArgs(PyObject *callable, ...)

返回值：新的引用。 Part of the Stable ABI.

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

成功时返回结果，在失败时抛出一个异常并返回 NULL。

这和Python表达式``callable(arg1, arg2, ...)``是一样的。

PyObject *PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)

返回值：新的引用。 Part of the Stable ABI.

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 PyObject* arguments. The arguments are provided as a variable number of parameters followed by NULL.

成功时返回结果，在失败时抛出一个异常并返回 NULL。

PyObject *PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)

调用 Python 对象 obj 中的一个方法并不附带任何参数，其中方法名称由 name 中的 Python 字符串对象给出。

成功时返回结果，在失败时抛出一个异常并返回 NULL。

3.9 新版功能.

PyObject *PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)

调用 Python 对象 obj 中的一个方法并附带单个位置参数 arg，其中方法名称由 name 中的 Python 字符串对象给出。

成功时返回结果，在失败时抛出一个异常并返回 NULL。

3.9 新版功能.

PyObject *PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

调用一个可调用的 Python 对象 callable。 附带的参数与 vectorcallfunc 相同。 如果 callable 支持 vectorcall，则它会直接调用存放在 callable 中的 vectorcall 函数。

成功时返回结果，在失败时抛出一个异常并返回 NULL。

3.9 新版功能.

PyObject *PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

调用 callable 并附带与在 vectorcall 协议中传入的完全相同的位置参数，但会加上以字典 kwdict 形式传入的关键字参数。 args 数组将只包含位置参数。

无论在内部使用哪种协议，都需要进行参数的转换。 因此，此函数应当仅在调用方已经拥有作为关键字参数的字典，但没有作为位置参数的元组时才被使用。

3.9 新版功能.

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 PY_VECTORCALL_ARGUMENTS_OFFSET if the value of args[0] may temporarily be changed. Keyword arguments can be passed just like in PyObject_Vectorcall().

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

成功时返回结果，在失败时抛出一个异常并返回 NULL。

3.9 新版功能.

调用支持 API

int PyCallable_Check(PyObject *o)

Part of the Stable ABI.

确定对象 o 是可调对象。如果对象是可调对象则返回 1 ，其他情况返回 0 。这个函数不会调用失败。