カプセル
********

これらのオブジェクトの使い方については 拡張モジュールに 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" を返します。
