# Call プロトコル

CPython supports two different calling protocols: tp_call and vectorcall.

## The tp_call Protocol

Instances of classes that set `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: `tp_new` and `tp_init` also pass arguments this way.

To call an object, use `PyObject_Call()` or another call API.

## The Vectorcall Protocol

Added in version 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 `PyObject_Call()`). Therefore, a class supporting vectorcall must also implement `tp_call`. Moreover, the callable must behave the same regardless of which protocol is used. The recommended way to achieve this is by setting `tp_call` to `PyVectorcall_Call()`. This bears repeating:

警告

A class supporting vectorcall must also implement `tp_call` with the same semantics.

バージョン 3.12 で変更: The `Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class when the class's `__call__()` method is reassigned. (This internally sets `tp_call` only, and thus may make it behave differently than the vectorcall function.) In earlier Python versions, vectorcall should only be used with `immutable` or static types.

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 `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)
  Part of the Stable ABI since version 3.12.

- 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

    `PY_VECTORCALL_ARGUMENTS_OFFSET` flag. To get the actual number of positional arguments from nargsf, use `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.

PY_VECTORCALL_ARGUMENTS_OFFSET
  Part of the Stable ABI since version 3.12.

  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 `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 `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.

  Added in version 3.8.

To call an object that implements vectorcall, use a call API function as with any other callable. `PyObject_Vectorcall()` will usually be most efficient.

注釈

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.

### 再帰の管理

When using tp_call, callees do not need to worry about recursion: CPython uses `Py_EnterRecursiveCall()` and `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

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)
  Part of the Stable ABI since version 3.12.

  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.

  Added in version 3.8.

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`.

  Added in version 3.9.

PyObject *PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)
  Part of the Stable ABI since version 3.12.

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

  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`.

  Added in version 3.8.

## 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.

関数 | callable | `args` | `kwargs`
--- | --- | --- | ---
`PyObject_Call()` | `PyObject *` | tuple | dict/`NULL`
`PyObject_CallNoArgs()` | `PyObject *` | --- | ---
`PyObject_CallOneArg()` | `PyObject *` | 1 object | ---
`PyObject_CallObject()` | `PyObject *` | tuple/`NULL` | ---
`PyObject_CallFunction()` | `PyObject *` | format | ---
`PyObject_CallMethod()` | obj + `char*` | format | ---
`PyObject_CallFunctionObjArgs()` | `PyObject *` | variadic | ---
`PyObject_CallMethodObjArgs()` | obj + name | variadic | ---
`PyObject_CallMethodNoArgs()` | obj + name | --- | ---
`PyObject_CallMethodOneArg()` | obj + name | 1 object | ---
`PyObject_Vectorcall()` | `PyObject *` | vectorcall | vectorcall
`PyObject_VectorcallDict()` | `PyObject *` | vectorcall | dict/`NULL`
`PyObject_VectorcallMethod()` | arg + name | vectorcall | vectorcall

PyObject *PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
  Return value: New reference. Part of the Stable ABI.

  呼び出し可能な Python のオブジェクト callable を、タプル args として与えられる引数と辞書 kwargs として与えられる名前付き引数とともに呼び出します。

  args は NULL であってはならず、引数を必要としない場合は空のタプルを使ってください。 kwargs は NULL でも構いません。

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

  これは次の Python の式と同等です: `callable(*args, **kwargs)` 。

PyObject *PyObject_CallNoArgs(PyObject *callable)
  Return value: New reference. Part of the Stable ABI since version 3.10.

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

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

  Added in version 3.9.

PyObject *PyObject_CallOneArg(PyObject *callable, PyObject *arg)
  Return value: New reference.

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

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

  Added in version 3.9.

PyObject *PyObject_CallObject(PyObject *callable, PyObject *args)
  Return value: New reference. Part of the Stable ABI.

  呼び出し可能な Python のオブジェクト callable を、タプル args として与えられる引数とともに呼び出します。 引数が必要な場合は、 args は NULL で構いません。

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

  これは次の Python の式と同等です: `callable(*args)` 。

PyObject *PyObject_CallFunction(PyObject *callable, const char *format, ...)
  Return value: New reference. Part of the Stable ABI.

  呼び出し可能な Python オブジェクト callable を可変数個の C 引数とともに呼び出します。 C 引数は `Py_BuildValue()` 形式のフォーマット文字列を使って記述します。 format は NULL かもしれず、与える引数がないことを表します。

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

  これは次の Python の式と同等です: `callable(*args)` 。

  PyObject* args だけを引数に渡す場合は、 `PyObject_CallFunctionObjArgs()` がより速い方法であることを覚えておいてください。

  バージョン 3.4 で変更: format の型が `char *` から変更されました。

PyObject *PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
  Return value: New reference. Part of the Stable ABI.

  オブジェクト obj の name という名前のメソッドを、いくつかの C 引数とともに呼び出します。 C 引数はタプルを生成する `Py_BuildValue()` 形式のフォーマット文字列で記述されています。

  format は NULL でもよく、引数が与えられないことを表します。

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

  これは次の Python の式と同等です: `obj.name(arg1, arg2, ...)` 。

  PyObject* args だけを引数に渡す場合は、 `PyObject_CallMethodObjArgs()` がより速い方法であることを覚えておいてください。

  バージョン 3.4 で変更: name と format の型が `char *` から変更されました。

PyObject *PyObject_CallFunctionObjArgs(PyObject *callable, ...)
  Return value: New reference. Part of the Stable ABI.

  呼び出し可能な Python オブジェクト callable を可変数個の PyObject* 引数とともに呼び出します。引数列は末尾に NULL がついた可変数個のパラメタとして与えます。

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

  これは次の Python の式と同等です: `callable(arg1, arg2, ...)` 。

PyObject *PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)
  Return value: New reference. Part of the Stable ABI.

  Python オブジェクト obj のメソッドを呼び出します、メソッド名は Python 文字列オブジェクト name で与えます。可変数個の PyObject* 引数と共に呼び出されます. 引数列は末尾に NULL がついた可変数個のパラメタとして与えます。

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

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.

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

  Added in version 3.9.

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.

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

  Added in version 3.9.

PyObject *PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
  Part of the Stable ABI since version 3.12.

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

  成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

  Added in version 3.9.

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.

  Added in version 3.9.

PyObject *PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
  Part of the Stable ABI since version 3.12.

  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 を返します。

  Added in version 3.9.

## Call Support API

int PyCallable_Check(PyObject *o)
  Part of the Stable ABI.

  オブジェクト o が呼び出し可能オブジェクトかどうか調べます。オブジェクトが呼び出し可能であるときに `1` を返し、そうでないときには `0` を返します。この関数呼び出しは常に成功します。