呼叫協定 (Call Protocol)¶
CPython 支援兩種不同的呼叫協定：tp_call 和 vectorcall（向量呼叫）。
tp_call 協定¶
設定 tp_call 的類別之實例都是可呼叫的。該插槽 (slot) 的簽章為：
PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);
要達成一個呼叫會使用一個 tuple（元組）表示位置引數、一個 dict 表示關鍵字引數，類似於 Python 程式碼中的 callable(*args, **kwargs)。args 必須不為 NULL（如果沒有引數，會使用一個空 tuple），但如果沒有關鍵字引數，kwargs 可以是 NULL。
這個慣例不僅會被 tp_call 使用，tp_new 和 tp_init 也這樣傳遞引數。
使用 PyObject_Call() 或其他呼叫 API 來呼叫一個物件。
Vectorcall 協定¶
在 3.9 版被加入.
Vectorcall 協定是在 PEP 590 被引入的，它是使函式呼叫更加有效率的附加協定。
經驗法則上，如果可呼叫物件有支援，CPython 於內部呼叫中會更傾向使用 vectorcall。然而，這並不是一個硬性規定。此外，有些第三方擴充套件會直接使用 tp_call（而不是使用 PyObject_Call()）。因此，一個支援 vectorcall 的類別也必須實作 tp_call。此外，無論使用哪種協定，可呼叫物件的行為都必須是相同的。要達成這個目的的推薦做法是將 tp_call 設定為 PyVectorcall_Call()。這值得一再提醒：
警告
一個支援 vectorcall 的類別必須也實作具有相同語義的 tp_call。
在 3.12 版的變更: 當一個類別的 __call__() 方法被重新賦值時，Py_TPFLAGS_HAVE_VECTORCALL 旗標現在會被移除。（這會在內部設定 tp_call，因此可能會使它與 vectorcall 函式有不同的行為。）在較早的 Python 版本中，vectorcall 應該只與 immutable 或靜態型別一起使用。
如果一個類別的 vectorcall 比 tp_call 慢，就不應該實作 vectorcall。例如，如果被呼叫者需要將引數轉換為 args tuple（引數元組）和 kwargs dict（關鍵字引數字典），那麼實作 vectorcall 就沒有意義。
類別可以透過啟用 Py_TPFLAGS_HAVE_VECTORCALL 旗標並將 tp_vectorcall_offset 設定為物件結構中有出現 vectorcallfunc 的 offset 來實作 vectorcall 協定。這是一個指向具有以下簽章之函式的指標：
-
typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)¶
- 為 穩定 ABI 的一部分 自 3.12 版本開始.
callable 是指被呼叫的物件。
- args 是一個 C 語言陣列 (array)，包含位置引數與後面
關鍵字引數的值。如果沒有引數，這個值可以是 NULL。
- nargsf 是位置引數的數量加上可能會有的
PY_VECTORCALL_ARGUMENTS_OFFSET旗標。如果要從 nargsf 獲得實際的位置引數數量，請使用PyVectorcall_NARGS()。
- kwnames 是一個包含所有關鍵字引數名稱的 tuple；
換句話說，就是 kwargs 字典的鍵。這些名字必須是字串（
str或其子類別的實例)，並且它們必須是不重複的。如果沒有關鍵字引數，那麼 kwnames 可以用 NULL 代替。
-
PY_VECTORCALL_ARGUMENTS_OFFSET¶
- 為 穩定 ABI 的一部分 自 3.12 版本開始.
如果在 vectorcall 的 nargsf 引數中設定了此旗標，則允許被呼叫者臨時更改
args[-1]的值。換句話說，args 指向向量中的引數 1（不是 0）。被呼叫方必須在回傳之前還原args[-1]的值。對於
PyObject_VectorcallMethod()，這個旗標的改變意味著可能是args[0]被改變。當可以以幾乎無代價的方式（無需佔據額外的記憶體）來達成，那麼會推薦呼叫者使用
PY_VECTORCALL_ARGUMENTS_OFFSET。這樣做會讓如 bound method（繫結方法）之類的可呼叫函式非常有效地繼續向前呼叫（這類函式包含一個在首位的 self 引數）。在 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)¶
- 為 穩定 ABI 的一部分 自 3.12 版本開始.
給定一個 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)¶
- 為 穩定 ABI 的一部分 自 3.12 版本開始.
呼叫 callable 的
vectorcallfunc，其位置引數和關鍵字引數分別以 tuple 和 dict 格式給定。這是一個專門函式，其目的是被放入
tp_call插槽或是用於tp_call的實作。它不會檢查Py_TPFLAGS_HAVE_VECTORCALL旗標並且它不會退回 (fall back) 使用tp_call。在 3.8 版被加入.
物件呼叫 API¶
有多個函式可被用來呼叫 Python 物件。各個函式會將其引數轉換為被呼叫物件所支援的慣用形式 – 可以是 tp_call 或 vectorcall。為了儘可能減少轉換的進行，請選擇一個適合你所擁有資料格式的函式。
下表總結了可用的函式；請參閱各個說明文件以瞭解詳情。
函式 |
callable |
args |
kwargs |
|---|---|---|---|
|
tuple |
dict/ |
|
|
--- |
--- |
|
|
一個物件 |
--- |
|
|
tuple/ |
--- |
|
|
format |
--- |
|
物件 + |
format |
--- |
|