カプセル

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

Added in version 3.1.

type PyCapsule

PyObject のこのサブタイプは不透明な値を表します。 C 拡張モジュールから Python のコードを経由して別の C コードへ、不透明な値を void* ポインタとして渡すのに役立ちます。 あるモジュールで定義した C 関数ポインタを別のモジュールに公開するためによく使われます。 これにより、通常のインポートの仕組みを使って、動的にロードしたモジュールの C API にアクセスできます。

PyTypeObject PyCapsule_Type

次に属します: Stable ABI.

カプセルオブジェクトに対応する型オブジェクトです。 Python レイヤの types.CapsuleType と同じオブジェクトです。

type PyCapsule_Destructor

次に属します: Stable ABI.

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

typedef void (*PyCapsule_Destructor)(PyObject *);

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

int PyCapsule_CheckExact(PyObject *p)

Thread safety: Atomic.

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

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

戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Atomic.

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. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

void *PyCapsule_GetContext(PyObject *capsule)

次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

const char *PyCapsule_GetName(PyObject *capsule)

次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

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

次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

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

この関数は name を . で分割し、最初の要素をインポートします。 残りの要素は属性の検索でたどります。

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

注釈

name がサブモジュールやサブパッケージの属性を指す場合、属性の検索を成功させるには、 事前に別の方法 (例えば PyImport_ImportModule()) でそのサブモジュールやサブパッケージをインポートしておく必要があります。

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

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

次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

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

次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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