カプセル
これらのオブジェクトの使用の詳細については、拡張モジュール用のCAPIの提供を参照してください。
バージョン3.1の新機能。
- type PyCapsule
- PyObject のこのサブタイプは不透明な値を表し、Pythonコードを介して他のCコードに不透明な値を( void * ポインターとして)渡す必要があるC拡張モジュールに役立ちます。 これは、あるモジュールで定義されたC関数ポインターを他のモジュールで使用できるようにするためによく使用されるため、通常のインポートメカニズムを使用して、動的にロードされたモジュールで定義されたCAPIにアクセスできます。
- type 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)
ポインタをカプセル化する PyCapsule を作成します。 ポインタ引数は
NULL
ではない可能性があります。失敗した場合は、例外を設定して
NULL
を返します。name 文字列は、
NULL
または有効なC文字列へのポインタのいずれかです。NULL
以外の場合、この文字列はカプセルよりも長持ちする必要があります。 (デストラクタ内で解放することは許可されていますが。)destructor 引数が
NULL
でない場合、カプセルが破棄されるときに引数としてカプセルが呼び出されます。このカプセルをモジュールの属性として保存する場合は、 name を
modulename.attributename
として指定する必要があります。 これにより、他のモジュールが PyCapsule_Import()を使用してカプセルをインポートできるようになります。
- void *PyCapsule_GetPointer(PyObject *capsule, const char *name)
カプセルに保存されているポインターを取得します。 失敗した場合は、例外を設定して
NULL
を返します。name パラメーターは、カプセルに格納されている名前と正確に比較する必要があります。 カプセルに保存されている名前が
NULL
の場合、渡される name もNULL
である必要があります。 Pythonは、C関数strcmp()
を使用してカプセル名を比較します。
- PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
カプセルに保存されている現在のデストラクタを返します。 失敗した場合は、例外を設定して
NULL
を返します。カプセルに
NULL
デストラクタを含めることは合法です。 これにより、NULL
の戻りコードがややあいまいになります。 PyCapsule_IsValid()または PyErr_Occurred()を使用して明確にします。
- void *PyCapsule_GetContext(PyObject *capsule)
カプセルに保存されている現在のコンテキストを返します。 失敗した場合は、例外を設定して
NULL
を返します。カプセルが
NULL
コンテキストを持つことは合法です。 これにより、NULL
の戻りコードがややあいまいになります。 PyCapsule_IsValid()または PyErr_Occurred()を使用して明確にします。
- const char *PyCapsule_GetName(PyObject *capsule)
カプセルに保存されている現在の名前を返します。 失敗した場合は、例外を設定して
NULL
を返します。カプセルに
NULL
の名前を付けることは合法です。 これにより、NULL
の戻りコードがややあいまいになります。 PyCapsule_IsValid()または PyErr_Occurred()を使用して明確にします。
- void *PyCapsule_Import(const char *name, int no_block)
モジュールのcapsule属性からCオブジェクトへのポインターをインポートします。 name パラメーターは、
module.attribute
のように、属性にフルネームを指定する必要があります。 カプセルに格納されている name は、この文字列と正確に一致する必要があります。 no_block がtrueの場合、ブロックせずにモジュールをインポートします( PyImport_ImportModuleNoBlock()を使用)。 no_block がfalseの場合は、通常どおりモジュールをインポートします( PyImport_ImportModule()を使用)。成功したら、カプセルの内部ポインターを返します。 失敗した場合は、例外を設定して
NULL
を返します。
- int PyCapsule_IsValid(PyObject *capsule, const char *name)
capsule が有効なカプセルであるかどうかを判別します。 有効なカプセルは非
NULL
であり、 PyCapsule_CheckExact()を渡し、非NULL
ポインターが格納されており、その内部名は name [ X158X]パラメータ。 (カプセル名の比較方法については、 PyCapsule_GetPointer()を参照してください。)つまり、 PyCapsule_IsValid()がtrue値を返す場合、任意のアクセサー(
PyCapsule_Get()
で始まる関数)の呼び出しは成功することが保証されます。オブジェクトが有効で、渡された名前と一致する場合は、ゼロ以外の値を返します。 それ以外の場合は
0
を返します。 この関数は失敗しません。
- int PyCapsule_SetContext(PyObject *capsule, void *context)
capsule 内のコンテキストポインタを context に設定します。
成功した場合は
0
を返します。 ゼロ以外を返し、失敗時に例外を設定します。
- int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
カプセル内のデストラクタをデストラクタに設定します。
成功した場合は
0
を返します。 ゼロ以外を返し、失敗時に例外を設定します。
- int PyCapsule_SetName(PyObject *capsule, const char *name)
capsule 内の名前を name に設定します。
NULL
以外の場合、名前はカプセルよりも長持ちする必要があります。 カプセルに保存されていた以前の名前がNULL
でなかった場合、それを解放する試みは行われません。成功した場合は
0
を返します。 ゼロ以外を返し、失敗時に例外を設定します。
- int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
capsule 内のvoidポインタを pointer に設定します。 ポインタが
NULL
でない可能性があります。成功した場合は
0
を返します。 ゼロ以外を返し、失敗時に例外を設定します。