カプセル

using-capsules 以下のオブジェクトを使う方法については 拡張モジュールに C API を提供する を参照してください。

バージョン 3.1 で追加.

PyCapsule

この PyObject のサブタイプは、任意の値を表し、C拡張モジュールから Pythonコードを経由して他のC言語のコードに任意の値を(void* ポインタの形で)渡す必要があるときに有用です。あるモジュール内で定義されているC言語関数のポインタを、他のモジュールに渡してそこから呼び出せるようにするためによく使われます。これにより、動的にロードされるモジュールの中の C API に通常の import 機構を通してアクセスすることができます。

PyCapsule_Destructor

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

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)
Return value: New reference.

Create a PyCapsule encapsulating the pointer. The pointer argument may not be NULL.

On failure, set an exception and return NULL.

The name string may either be NULL or a pointer to a valid C string. If non-NULL, this string must outlive the capsule. (Though it is permitted to free it inside the destructor.)

If the destructor argument is not NULL, it will be called with the capsule as its argument when it is destroyed.

このカプセルがモジュールの属性として保存される場合、 namemodulename.attributename と指定されるべきです。こうすると、他のモジュールがそのカプセルを PyCapsule_Import() でインポートすることができます。

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

Retrieve the pointer stored in the capsule. On failure, set an exception and return NULL.

The name parameter must compare exactly to the name stored in the capsule. If the name stored in the capsule is NULL, the name passed in must also be NULL. Python uses the C function strcmp() to compare capsule names.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

Return the current destructor stored in the capsule. On failure, set an exception and return NULL.

It is legal for a capsule to have a NULL destructor. This makes a NULL return code somewhat ambiguous; use PyCapsule_IsValid() or PyErr_Occurred() to disambiguate.

void* PyCapsule_GetContext(PyObject *capsule)

Return the current context stored in the capsule. On failure, set an exception and return NULL.

It is legal for a capsule to have a NULL context. This makes a NULL return code somewhat ambiguous; use PyCapsule_IsValid() or PyErr_Occurred() to disambiguate.

const char* PyCapsule_GetName(PyObject *capsule)

Return the current name stored in the capsule. On failure, set an exception and return NULL.

It is legal for a capsule to have a NULL name. This makes a NULL return code somewhat ambiguous; use PyCapsule_IsValid() or PyErr_Occurred() to disambiguate.

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

モジュールのカプセル属性から Cオブジェクトへのポインタをインポートします。 name 引数はその属性の完全名を module.attribute のように指定しなければなりません。カプセルに格納されている name はこの文字列に正確に一致しなければなりません。 no_block が真の時、モジュールを(PyImport_ImportModuleNoBlock() を使って) ブロックせずにインポートします。 no_block が偽の時、モジュールは (PyImport_ImportModule() を使って) 通常の方法でインポートされます。

Return the capsule's internal pointer on success. On failure, set an exception and return NULL.

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

Determines whether or not capsule is a valid capsule. A valid capsule is non-NULL, passes PyCapsule_CheckExact(), has a non-NULL pointer stored in it, and its internal name matches the name parameter. (See PyCapsule_GetPointer() for information on how capsule names are compared.)

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

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

int PyCapsule_SetContext(PyObject *capsule, void *context)

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

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

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

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

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

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

Set the name inside capsule to name. If non-NULL, the name must outlive the capsule. If the previous name stored in the capsule was not NULL, no attempt is made to free it.

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

Set the void pointer inside capsule to pointer. The pointer may not be NULL.

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