Capsules

有關使用這些物件的更多資訊，請參閱 為擴充套件模組提供 C API。

在 3.1 版本加入。

型別 PyCapsule

此 PyObject 子型別表示一個不透明值，對於需要透過 Python 程式碼將不透明值（作為 void* 指標）傳遞給其他 C 程式碼的 C 擴充套件模組非常有用。它通常用於將一個模組中定義的 C 函式指標提供給其他模組，以便可以使用常規的匯入機制來訪問動態載入模組中定義的 C API。

型別 PyCapsule_Destructor

作為 穩定 ABI 的一部分。

膠囊的解構函式回撥型別。定義為

typedef void (*PyCapsule_Destructor)(PyObject *);

有關 PyCapsule_Destructor 回撥的語義，請參閱 PyCapsule_New()。

int PyCapsule_CheckExact(PyObject *p)

如果其引數是 PyCapsule，則返回 true。此函式始終成功。

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

返回值: 新引用。 穩定ABI 的一部分。

建立一個封裝 pointer 的 PyCapsule。pointer 引數不能為 NULL。

失敗時，設定異常並返回 NULL。

name 字串可以是 NULL 或指向有效 C 字串的指標。如果非 NULL，此字串的生命週期必須長於膠囊。（儘管允許在 destructor 中釋放它。）

如果 destructor 引數不是 NULL，則當膠囊被銷燬時，它將以膠囊作為其引數被呼叫。

如果此膠囊將作為模組的屬性儲存，則 name 應指定為 modulename.attributename。這將使其他模組能夠使用 PyCapsule_Import() 匯入膠囊。

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)

作為 穩定 ABI 的一部分。

檢索儲存在膠囊中的 pointer。失敗時，設定異常並返回 NULL。

name 引數必須與儲存在膠囊中的名稱完全匹配。如果儲存在膠囊中的名稱是 NULL，則傳入的 name 也必須是 NULL。Python 使用 C 函式 strcmp() 比較膠囊名稱。

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

作為 穩定 ABI 的一部分。

返回儲存在膠囊中的當前解構函式。失敗時，設定異常並返回 NULL。

膠囊擁有 NULL 解構函式是合法的。這使得 NULL 返回程式碼有些模糊；請使用 PyCapsule_IsValid() 或 PyErr_Occurred() 來消除歧義。

void *PyCapsule_GetContext(PyObject *capsule)

作為 穩定 ABI 的一部分。

返回儲存在膠囊中的當前上下文。失敗時，設定異常並返回 NULL。

膠囊擁有 NULL 上下文是合法的。這使得 NULL 返回程式碼有些模糊；請使用 PyCapsule_IsValid() 或 PyErr_Occurred() 來消除歧義。

const char *PyCapsule_GetName(PyObject *capsule)

作為 穩定 ABI 的一部分。

返回儲存在膠囊中的當前名稱。失敗時，設定異常並返回 NULL。

膠囊擁有 NULL 名稱是合法的。這使得 NULL 返回程式碼有些模糊；請使用 PyCapsule_IsValid() 或 PyErr_Occurred() 來消除歧義。

void *PyCapsule_Import(const char *name, int no_block)

作為 穩定 ABI 的一部分。

從模組中的膠囊屬性匯入 C 物件的指標。name 引數應指定屬性的完整名稱，如 module.attribute。儲存在膠囊中的 name 必須與此字串完全匹配。

此函式在 . 字元處拆分 name，並匯入第一個元素。然後它使用屬性查詢處理後續元素。

成功時返回膠囊的內部 pointer。失敗時，設定異常並返回 NULL。

備註

如果 name 指向某個子模組或子包的屬性，則必須透過其他方式（例如，使用 PyImport_ImportModule()）預先匯入此子模組或子包，才能成功進行屬性查詢。

版本 3.3 中已更改: no_block 不再有任何作用。

int PyCapsule_IsValid(PyObject *capsule, const char *name)

作為 穩定 ABI 的一部分。

確定 capsule 是否是有效膠囊。有效膠囊非 NULL，透過 PyCapsule_CheckExact()，其中儲存的指標非 NULL，並且其內部名稱與 name 引數匹配。（有關如何比較膠囊名稱的資訊，請參閱 PyCapsule_GetPointer()。）

換句話說，如果 PyCapsule_IsValid() 返回真值，則保證對任何訪問器（所有以 PyCapsule_Get 開頭的函式）的呼叫都將成功。

如果物件有效並與傳入的名稱匹配，則返回非零值。否則返回 0。此函式不會失敗。

int PyCapsule_SetContext(PyObject *capsule, void *context)

作為 穩定 ABI 的一部分。

將 capsule 內部的上下文指標設定為 context。

成功時返回 0。失敗時返回非零並設定異常。

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

作為 穩定 ABI 的一部分。

將 capsule 內部的解構函式設定為 destructor。

成功時返回 0。失敗時返回非零並設定異常。

int PyCapsule_SetName(PyObject *capsule, const char *name)

作為 穩定 ABI 的一部分。

將 capsule 內部的名稱設定為 name。如果非 NULL，則名稱的生命週期必須長於膠囊。如果膠囊中儲存的先前 name 不是 NULL，則不會嘗試釋放它。

成功時返回 0。失敗時返回非零並設定異常。

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

作為 穩定 ABI 的一部分。

將 capsule 內部的 void 指標設定為 pointer。指標不能為 NULL。

成功時返回 0。失敗時返回非零並設定異常。