カプセル

これらのオブジェクトの使い方については 拡張モジュールに C API を提供する を参照してください。

Added in version 3.1.

type PyCapsule

This subtype of PyObject represents an opaque value, useful for C extension modules which need to pass an opaque value (as a void* pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically loaded modules.

PyTypeObject PyCapsule_Type

次に属します: Stable ABI.

The type object corresponding to capsule objects. This is the same object as types.CapsuleType in the Python layer.

type PyCapsule_Destructor

次に属します: Stable ABI.

カプセルに対するデストラクタコールバック型. 次のように定義されます:

typedef void (*PyCapsule_Destructor)(PyObject *);

PyCapsule_Destructor コールバックの動作については PyCapsule_New() を参照してください。

int PyCapsule_CheckExact(PyObject *p)

引数が PyCapsule の場合に真を返します。この関数は常に成功します。

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

戻り値: 新しい参照。 次に属します: Stable 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)

次に属します: Stable ABI.

カプセルに保存されている pointer を取り出します。失敗した場合は例外を設定して NULL を返します。

name 引数は、カプセルに格納されている名前と完全に一致しなければなりません。 カプセルに格納されている名前が NULL なら、渡す name も NULL でなければなりません。 Python はカプセル名の比較に C 関数 strcmp() を使います。

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

次に属します: Stable ABI.

カプセルに保存されている現在のデストラクタを返します。失敗した場合、例外を設定して NULL を返します。

カプセルは NULL をデストラクタとして持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred() を利用して確認してください。

void *PyCapsule_GetContext(PyObject *capsule)

次に属します: Stable ABI.

カプセルに保存されている現在のコンテキスト(context)を返します。失敗した場合、例外を設定して NULL を返します。

カプセルは NULL をコンテキストとして持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred() を利用して確認してください。

const char *PyCapsule_GetName(PyObject *capsule)

次に属します: Stable ABI.

カプセルに保存されている現在の name を返します。失敗した場合、例外を設定して NULL を返します。

カプセルは NULL を name として持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred() を利用して確認してください。

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

次に属します: Stable ABI.

モジュールのカプセル属性から、C オブジェクトへのポインタをインポートします。 name 引数には module.attribute のような属性の完全名を指定してください。 カプセルに格納されている name は、この文字列と完全に一致する必要があります。

This function splits name on the . character, and imports the first element. It then processes further elements using attribute lookups.

成功すると、カプセル内部の pointer を返します。 失敗すると例外を設定して NULL を返します。

注釈

If name points to an attribute of some submodule or subpackage, this submodule or subpackage must be previously imported using other means (for example, by using PyImport_ImportModule()) for the attribute lookups to succeed.

バージョン 3.3 で変更: no_block は効果を持たなくなりました。

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

次に属します: Stable ABI.

capsule が有効なカプセルであるかどうかをチェックします。有効な capsule は、非 NULL で、 PyCapsule_CheckExact() をパスし、非 NULL なポインタを格納していて、内部の name が引数 name とマッチします。 (name の比較方法については PyCapsule_GetPointer() を参照)

言い換えると、PyCapsule_IsValid() が真を返した場合、どのアクセサ (PyCapsule_Get で始まる関数) を呼び出しても成功することが保証されます。

オブジェクトが有効で name がマッチした場合に非 0 を、それ以外の場合に 0 を返します。この関数は絶対に失敗しません。

int PyCapsule_SetContext(PyObject *capsule, void *context)

次に属します: Stable ABI.

capsule 内部のコンテキストポインタを context に設定します。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

次に属します: Stable ABI.

capsule 内部のデストラクタを destructor に設定します。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

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

次に属します: Stable ABI.

capsule 内部の name を name に設定します。name が非 NULL のとき、それは capsule よりも長い寿命を持つ必要があります。もしすでに capsule に非 NULL の name が保存されていた場合、それに対する解放は行われません。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

次に属します: Stable ABI.

capsule 内部のポインタを pointer に設定します。pointer は NULL であってはなりません。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。