Call プロトコル
***************

CPython は *tp_call* と vectorcall の二つの呼び出しプロトコルをサポー
トしています。


*tp_call* プロトコル
====================

"tp_call" を設定したクラスのインスタンスは呼び出し可能です。 このスロ
ットのシグネチャは次のとおりです。

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

Python コードの "callable(*args, **kwargs)" と同様に、位置引数のタプル
とキーワード引数の辞書を使って呼び出します。 "args" は NULL であっては
いけません (引数がなければ空のタプルを使います)。 ただし、キーワード引
数がなければ "kwargs" は "NULL" で構いません。

この規約は *tp_call* だけでなく、"tp_new" と "tp_init" で引数を渡すと
きにも使います。

オブジェクトを呼び出すには "PyObject_Call()" または別の 呼び出し API
を使ってください。


vectorcall プロトコル
=====================

Added in version 3.9.

vectorcall プロトコルは、呼び出しを効率化するための追加のプロトコルと
して **PEP 590** で導入されました。

目安として、呼び出し可能オブジェクトが vectorcall をサポートしていれば
、CPython は内部の呼び出しでそれを優先します。 ただし、厳密な規則では
ありません。 また、サードパーティの拡張の中には "PyObject_Call()" を使
わずに *tp_call* を直接使うものもあります。 そのため、vectorcall をサ
ポートするクラスは "tp_call" も実装する必要があります。 さらに、どちら
のプロトコルでも同じ動作をしなければなりません。 これを実現するために
推奨される方法は、"tp_call" を "PyVectorcall_Call()" に設定することで
す。 繰り返しますが、次の点が重要です。

警告:

  vectorcall をサポートするクラスは、同じ意味を持つ "tp_call" も **必
  ず** 実装しなければなりません。

バージョン 3.12 で変更: クラスの "__call__()" メソッドが再代入されると
、そのクラスから "Py_TPFLAGS_HAVE_VECTORCALL" フラグを取り除くようにな
りました。 (この再代入は内部で "tp_call" だけを設定するため、
vectorcall 関数と動作が異なる可能性があります。) 以前の Python では、
vectorcall は "不変な型" または静的な型でのみ使うべきです。

*tp_call* より遅くなる場合、クラスは vectorcall を実装すべきではありま
せん。 例えば、呼び出される側が結局引数を args タプルと kwargs 辞書に
変換する必要があるなら、vectorcall を実装する意味はありません。

クラスは "Py_TPFLAGS_HAVE_VECTORCALL" フラグを有効にし、
"tp_vectorcall_offset" をオブジェクト構造体内の *vectorcallfunc* の位
置のオフセットに設定することで、vectorcall プロトコルを実装できます。
これは次のシグネチャを持つ関数へのポインタです。

typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
    * 次に属します: Stable ABI (バージョン 3.12 より).*

* "callable" は呼び出されるオブジェクトです。

* *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
    * 次に属します: Stable ABI (バージョン 3.12 より).*

   vectorcall の "nargsf" 引数にこのフラグが設定されている場合、呼び出
   される側は一時的に "args[-1]" を変更できます。 つまり、"args" は割
   り当てられたベクトル内の引数 0 ではなく引数 1 を指します。 呼び出さ
   れる側は、戻る前に "args[-1]" の値を元に戻す必要があります。

   "PyObject_VectorcallMethod()" の場合、このフラグは代わりに
   "args[0]" を変更してよいことを意味します。

   追加の割り当てなしに低コストで設定できる場合、呼び出し側は
   "PY_VECTORCALL_ARGUMENTS_OFFSET" を使うことが推奨されます。 これに
   より、束縛メソッドなどの呼び出し可能オブジェクトは、先頭に "self"
   引数を追加して次の呼び出しを行う処理を非常に効率的に実行できます。

   Added in version 3.8.

vectorcall を実装するオブジェクトを呼び出すには、ほかの呼び出し可能オ
ブジェクトと同様に 呼び出し API の関数を使ってください。 通常は
"PyObject_Vectorcall()" が最も効率的です。


再帰の管理
----------

*tp_call* を使う場合、呼び出される側は 再帰 を管理する必要はありません
。 CPython は *tp_call* による呼び出しで "Py_EnterRecursiveCall()" と
"Py_LeaveRecursiveCall()" を使います。

効率のため、vectorcall による呼び出しではこの管理を行いません。 必要に
応じて、呼び出される側が "Py_EnterRecursiveCall()" と
"Py_LeaveRecursiveCall()" を使ってください。


vectorcall サポート API
-----------------------

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)
    * 次に属します: Stable ABI (バージョン 3.12 より).*

   vectorcall の "nargsf" 引数から、実際の引数の数を返します。 現在は
   次と同等です。

      (Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)

   ただし、将来の拡張に対応するため、関数 "PyVectorcall_NARGS" を使っ
   てください。

   Added in version 3.8.

vectorcallfunc PyVectorcall_Function(PyObject *op)

   "op" が vectorcall プロトコルをサポートしていなければ (型がサポート
   していない場合も、そのインスタンスがサポートしていない場合も)
   "NULL" を返します。 それ以外の場合は、"op" に格納された vectorcall
   関数ポインタを返します。 この関数が例外を送出することはありません。

   主に、"op" が vectorcall をサポートするかどうかを確認するのに便利で
   す。 "PyVectorcall_Function(op) != NULL" で確認できます。

   Added in version 3.9.

PyObject *PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)
    * 次に属します: Stable ABI (バージョン 3.12 より).*

   それぞれタプルと辞書で与えられた位置引数とキーワード引数を使い、
   "callable" の "vectorcallfunc" を呼び出します。

   この特殊用途の関数は、"tp_call" スロットに設定するか、"tp_call" の
   実装内で使うためのものです。 "Py_TPFLAGS_HAVE_VECTORCALL" フラグを
   確認せず、"tp_call" へのフォールバックも行いません。

   Added in version 3.8.


オブジェクト呼び出し API
========================

Python オブジェクトを呼び出すためのさまざまな関数があります。 各関数は
、呼び出すオブジェクトがサポートする *tp_call* または vectorcall の規
約に引数を変換します。 変換を最小限にするため、手元のデータの形式に最
も合う関数を選んでください。

利用できる関数を以下の表にまとめます。 詳細は個別の説明を参照してくだ
さい。

+--------------------------------------------+--------------------+----------------------+-----------------+
| 関数                                       | callable           | "args"               | "kwargs"        |
|============================================|====================|======================|=================|
| "PyObject_Call()"                          | "PyObject *"       | tuple                | dict/"NULL"     |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_CallNoArgs()"                    | "PyObject *"       | ---                  | ---             |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_CallOneArg()"                    | "PyObject *"       | 1 個のオブジェクト   | ---             |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_CallObject()"                    | "PyObject *"       | tuple/"NULL"         | ---             |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_CallFunction()"                  | "PyObject *"       | format               | ---             |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_CallMethod()"                    | obj + "char*"      | format               | ---             |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_CallFunctionObjArgs()"           | "PyObject *"       | 可変長引数           | ---             |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_CallMethodObjArgs()"             | obj + 名前         | 可変長引数           | ---             |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_CallMethodNoArgs()"              | obj + 名前         | ---                  | ---             |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_CallMethodOneArg()"              | obj + 名前         | 1 個のオブジェクト   | ---             |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_Vectorcall()"                    | "PyObject *"       | vectorcall           | vectorcall      |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_VectorcallDict()"                | "PyObject *"       | vectorcall           | dict/"NULL"     |
+--------------------------------------------+--------------------+----------------------+-----------------+
| "PyObject_VectorcallMethod()"              | arg + 名前         | vectorcall           | vectorcall      |
+--------------------------------------------+--------------------+----------------------+-----------------+

PyObject *PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

   "args" は "NULL" であってはいけません。 引数が不要な場合は空のタプ
   ルを使ってください。 キーワード引数が不要な場合は "kwargs" を
   "NULL" にできます。

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

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

PyObject *PyObject_CallNoArgs(PyObject *callable)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.10
   より).*

   呼び出し可能な Python オブジェクト "callable" を引数なしで呼び出し
   ます。 引数なしで呼び出すには最も効率的な方法です。

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

   Added in version 3.9.

PyObject *PyObject_CallOneArg(PyObject *callable, PyObject *arg)
    *戻り値: 新しい参照。*

   呼び出し可能な Python オブジェクト "callable" を、位置引数 "arg" だ
   けを渡し、キーワード引数なしで呼び出します。

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

   Added in version 3.9.

PyObject *PyObject_CallObject(PyObject *callable, PyObject *args)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   呼び出し可能な Python オブジェクト "callable" を、タプル "args" で
   与えられた引数で呼び出します。 引数が不要な場合は "args" を "NULL"
   にできます。

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

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

PyObject *PyObject_CallFunction(PyObject *callable, const char *format, ...)
    *戻り値: 新しい参照。** 次に属します: 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, ...)
    *戻り値: 新しい参照。** 次に属します: 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, ...)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

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

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

PyObject *PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

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

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

   Python オブジェクト "obj" のメソッドを引数なしで呼び出します。 メソ
   ッド名は Python 文字列オブジェクト "name" で指定します。

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

   Added in version 3.9.

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

   Python オブジェクト "obj" のメソッドを、一つの位置引数 "arg" を渡し
   て呼び出します。 メソッド名は Python 文字列オブジェクト "name" で指
   定します。

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

   Added in version 3.9.

PyObject *PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
    * 次に属します: Stable ABI (バージョン 3.12 より).*

   呼び出し可能な Python オブジェクト "callable" を呼び出します。 引数
   は "vectorcallfunc" と同じです。 "callable" が vectorcall をサポー
   トしている場合は、"callable" に格納された vectorcall 関数を直接呼び
   出します。

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

   Added in version 3.8: "_PyObject_Vectorcall" として追加。

   バージョン 3.9 で変更: 先頭のアンダースコアを取り除いた現在の名前に
   変更しました。 以前の暫定的な名前は *緩やかに非推奨* です。

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

   位置引数は vectorcall プロトコルとまったく同じ方法で渡し、キーワー
   ド引数は辞書 "kwdict" で渡して "callable" を呼び出します。 "args"
   配列には位置引数だけを含めます。

   内部でどちらのプロトコルを使っても、引数の変換が必要です。 そのため
   、この関数は呼び出し側がキーワード引数の辞書をすでに用意していて、
   位置引数のタプルは持っていない場合だけに使ってください。

   Added in version 3.9.

PyObject *PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
    * 次に属します: Stable ABI (バージョン 3.12 より).*

   vectorcall の呼び出し規約でメソッドを呼び出します。 メソッド名は
   Python 文字列 "name" で指定します。 メソッドを呼び出す対象のオブジ
   ェクトは "args[0]" で、"args[1]" から始まる "args" 配列が呼び出しの
   引数を表します。 位置引数は少なくとも一つ必要です。 "nargsf" は
   "args[0]" を含む位置引数の数で、"args[0]" の値を一時的に変更してよ
   い場合は "PY_VECTORCALL_ARGUMENTS_OFFSET" を加えます。 キーワード引
   数は "PyObject_Vectorcall()" と同じ方法で渡せます。

   オブジェクトが "Py_TPFLAGS_METHOD_DESCRIPTOR" の機能を持つ場合、
   "args" ベクトル全体を引数として非束縛メソッドオブジェクトを呼び出し
   ます。

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

   Added in version 3.9.


呼び出しサポート API
====================

int PyCallable_Check(PyObject *o)
    * 次に属します: Stable ABI.*

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