モジュールオブジェクト (module object)
**************************************

PyTypeObject PyModule_Type
    * 次に属します: Stable ABI.*

   この "PyTypeObject" のインスタンスは Python のモジュール型を表しま
   す。 Python プログラムには "types.ModuleType" として公開されていま
   す。

int PyModule_Check(PyObject *p)

   *p* がモジュールオブジェクトかモジュールオブジェクトのサブタイプで
   あるときに真を返します。この関数は常に成功します。

int PyModule_CheckExact(PyObject *p)

   *p* がモジュールオブジェクトで、かつ "PyModule_Type" のサブタイプで
   ないときに真を返します。この関数は常に成功します。

PyObject *PyModule_NewObject(PyObject *name)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.7
   より).*

   "module.__name__" に *name* を設定した新しいモジュールオブジェクト
   を返します。 モジュールの "__name__"、"__doc__"、"__package__"、
   "__loader__" 属性を設定します ("__name__" 以外はすべて "None" に設
   定します)。 "__file__" 属性の設定は呼び出し側の責任です。

   エラー時には例外を設定して "NULL" を返します。

   Added in version 3.3.

   バージョン 3.4 で変更: "__package__" と "__loader__" を "None" に設
   定するようになりました。

PyObject *PyModule_New(const char *name)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   "PyModule_NewObject()" に似ていますが、 name は Unicode オブジェク
   トではなく UTF-8 でエンコードされた文字列です。

PyObject *PyModule_GetDict(PyObject *module)
    *戻り値: 借用参照。** 次に属します: Stable ABI.*

   *module* の名前空間を実装する辞書オブジェクトを返します; このオブジ
   ェクトは、モジュールオブジェクトの "__dict__" 属性と同じものです。
   *module* がモジュールオブジェクト (もしくはモジュールオブジェクトの
   サブタイプ) でない場合は、 "SystemError" が送出され "NULL" が返され
   ます。

   拡張モジュールでは、モジュールの "__dict__" を直接操作するよりも、
   "PyModule_*" および "PyObject_*" 関数を使う方が推奨されます。

   返す参照はモジュールからの借用参照であり、モジュールが破棄されるま
   で有効です。

PyObject *PyModule_GetNameObject(PyObject *module)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.7
   より).*

   *module* の "__name__" の値を返します。 この属性がない場合や文字列
   でない場合は、"SystemError" を送出して "NULL" を返します。

   Added in version 3.3.

const char *PyModule_GetName(PyObject *module)
    * 次に属します: Stable ABI.*

   "PyModule_GetNameObject()" に似ていますが、 "'utf-8'" でエンコード
   された name を返します。

   返されたバッファは、モジュールの名前が変更されるかモジュールが破棄
   されるまで有効です。 Python コードから "__name__" 属性を設定してモ
   ジュール名を変更できることに注意してください。

PyModuleDef *PyModule_GetDef(PyObject *module)
    * 次に属します: Stable ABI.*

   モジュールが作られる元となった "PyModuleDef" 構造体へのポインタを返
   します。 モジュールが定義によって作られていなかった場合は "NULL" を
   返します。

   エラー時には例外を設定して "NULL" を返します。 "PyErr_Occurred()"
   を使って、"PyModuleDef" がない場合と区別してください。

PyObject *PyModule_GetFilenameObject(PyObject *module)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   *module* の "__file__" 属性を使って、*module* をロードしたファイル
   の名前を返します。 この属性が定義されていない場合や文字列でない場合
   は、"SystemError" を送出して "NULL" を返します。 それ以外の場合は
   Unicode オブジェクトへの参照を返します。

   Added in version 3.2.

const char *PyModule_GetFilename(PyObject *module)
    * 次に属します: Stable ABI.*

   "PyModule_GetFilenameObject()" と似ていますが、 'utf-8' でエンコー
   ドされたファイル名を返します。

   返されたバッファは、モジュールの "__file__" 属性に別の値が代入され
   るか、モジュールが破棄されるまで有効です。

   バージョン 3.2 で非推奨: "PyModule_GetFilename()" はエンコードでき
   ないファイル名に対しては "UnicodeEncodeError" を送出します。これの
   代わりに "PyModule_GetFilenameObject()" を使用してください。


モジュールの定義
================

C API で作成するモジュールは通常、"PySlot" 構造体の配列を使って定義し
ます。 この配列はモジュールの作成方法を「記述」します。 スロット全般に
ついては 定義用スロット を参照してください。

バージョン 3.15 で変更: 以前はモジュールの定義に "PyModuleDef" 構造体
が必要でした。 従来のモジュール定義方法も引き続き利用できます。 以前の
Python バージョンに対応する場合は、モジュール定義構造体 の節または以前
のバージョンのドキュメントを参照してください。

スロット配列は通常、拡張モジュールの「メイン」のモジュールオブジェクト
の定義に使います (詳細は 拡張モジュールの定義 を参照)。 拡張モジュール
を動的に作成する こともできます。

特に指定がない限り、スロット配列内で同じスロット ID を繰り返し使っては
いけません。


メタデータのスロット
--------------------

Py_mod_name
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   新しいモジュールの名前を指定する "スロット ID" です。 値は UTF-8 で
   エンコードされた NUL 終端の "const char *" です。

   モジュールは通常 "ModuleSpec" を使って作成され、その場合は
   "Py_mod_name" ではなく spec の名前を使うことに注意してください。 た
   だし、イントロスペクションやデバッグのため、このスロットを含めるこ
   とを推奨します。

   Added in version 3.15: 以前のバージョンに対応するには、代わりに
   "PyModuleDef.m_name" を使ってください。

Py_mod_doc
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   新しいモジュールの docstring を指定する "スロット ID" です。 値は
   UTF-8 でエンコードされた NUL 終端の "const char *" です。

   通常は "PyDoc_STRVAR" で作成した変数を設定します。

   Added in version 3.15: 以前のバージョンに対応するには、代わりに
   "PyModuleDef.m_doc" を使ってください。


対応機能のスロット
------------------

Py_mod_abi
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   拡張モジュールが使う ABI を記述する "PyABIInfo" 構造体へのポインタ
   を値とする "スロット ID" です。

   "PyABIInfo_VAR" マクロを使うと、適切な "PyABIInfo" 変数を次のように
   定義できます:

      PyABIInfo_VAR(abi_info);

      static PySlot mymodule_slots[] = {
         PySlot_DATA(Py_mod_abi, &abi_info),
         ...
      };

   モジュールの作成時に、Python は "PyABIInfo_Check()" でこのスロット
   の値を検査します。

   "PyModuleDef" から作成するモジュールを除き、このスロットは必須です
   。

   Added in version 3.15.

Py_mod_multiple_interpreters
    * 次に属します: Stable ABI (バージョン 3.12 より).*

   次のいずれかを値とする "スロット ID" です:

   Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED

      モジュールはサブインタープリタでのインポートに対応していません。

   Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

      モジュールはサブインタープリタでのインポートに対応していますが、
      メインインタープリタの GIL を共有している場合に限ります (拡張モ
      ジュールを分離する を参照)。

   Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

      モジュールは、サブインタープリタが独自の GIL を持つ場合も、サブ
      インタープリタでのインポートに対応しています (拡張モジュールを分
      離する を参照)。

   このスロットは、このモジュールをサブインタープリタでインポートする
   と失敗するかどうかを決めます。

   "Py_mod_multiple_interpreters" を指定しない場合、インポート機構はデ
   フォルトで "Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED" を使います。

   歴史的な理由により、値はポインタ ("void *") として宣言されています
   。 "PySlot" 配列を使う場合、"Py_mod_multiple_interpreters" には
   "PySlot_DATA" を使ってください:

      PySlot_DATA(Py_mod_multiple_interpreters,
                  Py_MOD_PER_INTERPRETER_GIL_SUPPORTED)

   Added in version 3.12.

Py_mod_gil
    * 次に属します: Stable ABI (バージョン 3.13 より).*

   次のいずれかを値とする "スロット ID" です:

   Py_MOD_GIL_USED

      モジュールはグローバルインタープリタロック (GIL) の存在に依存し
      、同期せずにグローバルな状態にアクセスする場合があります。

   Py_MOD_GIL_NOT_USED

      モジュールは GIL が有効でなくても安全に実行できます。

   "--disable-gil" を指定せずに構成した Python ビルドでは、このスロッ
   トは無視されます。 それ以外のビルドでは、このモジュールのインポート
   によって GIL が自動的に有効になるかどうかを決めます。 詳細は フリー
   スレッドの CPython を参照してください。

   "Py_mod_gil" を指定しない場合、インポート機構はデフォルトで
   "Py_MOD_GIL_USED" を使います。

   歴史的な理由により、値はポインタ ("void *") として宣言されています
   。 "PySlot" 配列を使う場合、"Py_mod_gil" には "PySlot_DATA" を使っ
   てください:

      PySlot_DATA(Py_mod_gil, Py_MOD_GIL_NOT_USED)

   Added in version 3.13.


作成と初期化のスロット
----------------------

Py_mod_create
    * 次に属します: Stable ABI (バージョン 3.5 より).*

   モジュールオブジェクト自体を作成する関数を指定する "スロット ID" で
   す。 関数は次のシグネチャを持つ必要があります:

   PyObject *create_module(PyObject *spec, PyModuleDef *def)

   関数には次の引数を渡します:

   * *spec*: "ModuleSpec" に似たオブジェクトです。 つまり、
     "importlib.machinery.ModuleSpec" で定義される属性はそれぞれ同じ意
     味を持ちます。 ただし、どの属性も存在しない場合があります。

   * *def*: "NULL"、またはモジュールをモジュール定義から作成する場合は
     その定義です。

   この関数は、新しいモジュールオブジェクトを返すか、エラーを設定して
   "NULL" を返す必要があります。

   この関数の処理は最小限に留めてください。 特に、同じモジュールを再び
   インポートしようとすると無限ループに陥る可能性があるため、任意の
   Python コードを呼び出してはいけません。

   "Py_mod_create" が設定されていない場合は、インポート機構は
   "PyModule_New()" を使って通常のモジュールオブジェクトを生成します。
   モジュールの名前は定義ではなく *spec* から取得され、これによって拡
   張モジュールが動的にモジュール階層における位置を調整できたり、シン
   ボリックリンクを通して同一のモジュール定義を共有しつつ別の名前でイ
   ンポートできたりします。

   返すオブジェクトは "PyModule_Type" のインスタンスである必要はありま
   せん。 ただし、一部のスロットは "PyModule_Type" のインスタンスでし
   か使えません。 特に以下のスロットが該当します:

   * "Py_mod_exec"、

   * モジュール状態のスロット ("Py_mod_state_*")、

   * "Py_mod_token"。

   Added in version 3.5.

   バージョン 3.15 で変更: The *slots* argument may be a
   "ModuleSpec"-like object, rather than a true "ModuleSpec" instance.
   Note that previous versions of CPython did not enforce this.モジュ
   ールは必ずしもモジュール定義から作成されるとは限らないため、*def*
   引数に "NULL" を指定できるようになりました。

Py_mod_exec
    * 次に属します: Stable ABI (バージョン 3.5 より).*

   モジュールを *実行*、つまり初期化する関数を指定する "スロット ID"
   です。 この関数は Python モジュールのコード実行に相当する処理を行い
   ます。 通常はモジュールにクラスや定数を追加します。 関数のシグネチ
   ャは次のとおりです:

   int exec_module(PyObject *module)

   この関数から呼び出すと便利な関数については、サポート関数 の節を参照
   してください。

   後方互換性のため、"PyModuleDef.m_slots" 配列には複数の
   "Py_mod_exec" スロットを含めることができ、配列内の順序で処理します
   。 それ以外 (つまり "PyModule_FromSlotsAndSpec()" の引数や
   "PyModExport_*<name>*" の戻り値) では、このスロットを繰り返してはい
   けません。

   Added in version 3.5.

   バージョン 3.15 で変更: "PyModuleDef.m_slots" を除き、"Py_mod_exec"
   スロットの重複が禁止されました。

Py_mod_methods
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   モジュールレベルの関数のテーブルを指定する "スロット ID" です。 値
   は "PyModule_AddFunctions()" の *functions* 引数に渡せる
   "PyMethodDef" 値の配列です。

   他のスロット ID と同様に、スロット配列に含められる "Py_mod_methods"
   エントリーは 1 つだけです。 複数の "PyMethodDef" 配列から関数を追加
   するには、"Py_mod_exec" 関数内で "PyModule_AddFunctions()" を呼び出
   してください。

   テーブルは静的に割り当てる必要があります (または、モジュールオブジ
   ェクトより長く存続することを別の方法で保証する必要があります)。

   Added in version 3.15: 以前のバージョンに対応するには、代わりに
   "PyModuleDef.m_methods" を使ってください。


モジュール状態
==============

拡張モジュールは *モジュール状態* を持つことができます。 これはモジュ
ール作成時に割り当てられ、モジュールオブジェクトの解放時に解放されるメ
モリ領域です。 モジュール状態は 専用のスロット で指定します。

モジュール状態の典型的な用途は、例外型や、モジュールで定義する *あらゆ
る* 型オブジェクトの保持です。

モジュールの Python 属性とは異なり、モジュール状態に保持したデータを
Python コードから置き換えたり削除したりすることはできません。

モジュールごとの情報を静的なグローバル変数ではなく属性とモジュール状態
に保持すると、モジュールオブジェクトが *分離* され、複数のサブインター
プリタでより安全に使えます。 また、Python が終了時に適切な順序で後始末
を行う助けにもなります。

モジュール状態の一部として Python オブジェクトへの参照を保持する拡張モ
ジュールは、参照のリークを防ぐため、"Py_mod_state_traverse" 関数と
"Py_mod_state_clear" 関数を実装する必要があります。

指定されたモジュールから状態を取得するには、次の関数を使います:

void *PyModule_GetState(PyObject *module)
    * 次に属します: Stable ABI.*

   モジュールの「状態」、つまりモジュールの作成時に割り当てられたメモ
   リ領域へのポインタ、または "NULL" を返します。 "Py_mod_state_size"
   を参照してください。

   エラー時には例外を設定して "NULL" を返します。 "PyErr_Occurred()"
   を使って、モジュール状態がない場合と区別してください。

int PyModule_GetStateSize(PyObject *module, Py_ssize_t *result)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   **result* に、"Py_mod_state_size" (または "PyModuleDef.m_size") で
   指定された *module* の状態のサイズを設定し、0 を返します。

   エラー時には **result* に -1 を設定し、例外を設定して -1 を返します
   。

   Added in version 3.15.


モジュール状態を定義するスロット
--------------------------------

モジュール状態の定義には、次の "スロット ID" を使えます。

Py_mod_state_size
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   モジュール状態のバイト単位のサイズを指定する "スロット ID" です。

   非負の値を設定すると、モジュールを再初期化できることを示すとともに
   、その状態のために必要な追加メモリの量を指定します。

   詳細は **PEP 3121** を参照。

   指定したモジュールの状態のサイズを取得するには、
   "PyModule_GetStateSize()" を使ってください。

   Added in version 3.15: 以前のバージョンに対応するには、代わりに
   "PyModuleDef.m_size" を使ってください。

Py_mod_state_traverse
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   GC がモジュールオブジェクトの参照をたどる際に呼び出す走査関数を指定
   する "スロット ID" です。

   関数のシグネチャと引数の意味は、"PyTypeObject.tp_traverse" と同様で
   す:

   int traverse_module_state(PyObject *module, visitproc visit, void *arg)

   モジュール状態が要求されていても、まだ割り当てられていなければ、こ
   の関数は呼び出されません。 モジュールの作成直後で、モジュールの実行
   ("Py_mod_exec" 関数) の前がこれに該当します。 より正確には、状態の
   サイズ ("Py_mod_state_size") が 0 より大きく、モジュール状態
   ("PyModule_GetState()" の戻り値) が "NULL" の場合、この関数は呼び出
   されません。

   Added in version 3.15: 以前のバージョンに対応するには、代わりに
   "PyModuleDef.m_traverse" を使ってください。

Py_mod_state_clear
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   GC がモジュールオブジェクトをクリアする際に呼び出すクリア関数を指定
   する "スロット ID" です。

   関数のシグネチャは次のとおりです:

   int clear_module_state(PyObject *module)

   モジュール状態が要求されていても、まだ割り当てられていなければ、こ
   の関数は呼び出されません。 モジュールの作成直後で、モジュールの実行
   ("Py_mod_exec" 関数) の前がこれに該当します。 より正確には、状態の
   サイズ ("Py_mod_state_size") が 0 より大きく、モジュール状態
   ("PyModule_GetState()" の戻り値) が "NULL" の場合、この関数は呼び出
   されません。

   "PyTypeObject.tp_clear" と同様に、この関数はモジュールの解放前に *
   必ず* 呼び出されるわけではありません。 例えば、参照カウントだけでオ
   ブジェクトが使われなくなったと判断できる場合、循環ガベージコレクタ
   は関与せず、"Py_mod_state_free" 関数が直接呼び出されます。

   Added in version 3.15: 以前のバージョンに対応するには、代わりに
   "PyModuleDef.m_clear" を使ってください。

Py_mod_state_free
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   モジュールオブジェクトの解放時に呼び出す関数を指定する "スロット
   ID" です。

   関数のシグネチャは次のとおりです:

   int free_module_state(PyObject *module)

   モジュール状態が要求されていても、まだ割り当てられていなければ、こ
   の関数は呼び出されません。 モジュールの作成直後で、モジュールの実行
   ("Py_mod_exec" 関数) の前がこれに該当します。 より正確には、状態の
   サイズ ("Py_mod_state_size") が 0 より大きく、モジュール状態
   ("PyModule_GetState()" の戻り値) が "NULL" の場合、この関数は呼び出
   されません。

   Added in version 3.15: 以前のバージョンに対応するには、代わりに
   "PyModuleDef.m_free" を使ってください。


モジュールトークン
------------------

各モジュールには、*トークン* を関連づけることができます。 これはモジュ
ール状態のメモリレイアウトを識別するための、ポインタサイズの値です。
つまり、手元のモジュールオブジェクトが自分の拡張モジュールに「属する」
かどうか不明な場合は、次のようなコードで確認できます:

   PyObject *module = <the module in question>

   void *module_token;
   if (PyModule_GetToken(module, &module_token) < 0) {
       return NULL;
   }
   if (module_token != your_token) {
       PyErr_SetString(PyExc_ValueError, "unexpected module")
       return NULL;
   }

   // This module's state has the expected memory layout; it's safe to cast
   struct my_state state = (struct my_state*)PyModule_GetState(module)

モジュールのトークン、つまり上のコードの *your_token* に使う値は次のと
おりです:

* "PyModuleDef" を使って作成したモジュールでは、その "PyModuleDef" の
  アドレスです。

* "Py_mod_token" スロットを使って定義したモジュールでは、そのスロット
  の値です。

* "PyModExport_*" エクスポートフック から作成したモジュールでは、エク
  スポートフックが返したスロット配列です ("Py_mod_token" でオーバーラ
  イドした場合を除きます)。

Py_mod_token
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   モジュールトークンを指定する "スロット ID" です。

   デフォルトに任せず、このスロットでモジュールトークンを設定する場合
   は、以下を保証する必要があります:

   * クラスが存在する間にポインタが他の用途に再利用されないよう、その
     参照先がクラスより長く存続すること。

   * 他の拡張モジュールと競合しないよう、クラスが属する拡張モジュール
     にそのポインタが「属する」こと。

   * トークンが "PyModuleDef" 構造体を指している場合、モジュールはその
     "PyModuleDef" から作成した場合と同じように動作する必要があります
     。 特に、モジュール状態のレイアウトと意味が一致していなければなり
     ません。

   "PyModuleDef" から作成したモジュールは、常にその "PyModuleDef" のア
   ドレスをトークンに使います。 そのため、"Py_mod_token" を
   "PyModuleDef.m_slots" で使うことはできません。

   Added in version 3.15.

int PyModule_GetToken(PyObject *module, void **result)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   **result* に *module* のモジュールトークンを設定し、0 を返します。

   エラー時には **result* に "NULL" を設定し、例外を設定して -1 を返し
   ます。

   Added in version 3.15.

"PyType_GetModuleByToken()" も参照してください。


拡張モジュールの動的な作成
==========================

次の関数を使うと、拡張モジュールの エクスポートフック を使わず、動的に
拡張モジュールを作成できます。

PyObject *PyModule_FromSlotsAndSpec(const PySlot *slots, PyObject *spec)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.15
   より).*

   スロット の配列と "ModuleSpec" *spec* から、新しいモジュールオブジ
   ェクトを作成します。

   *slots* 引数は、スロット ID が 0 のエントリー (通常は "PySlot_END"
   と記述します) で終端された "PySlot" 構造体の配列を指す必要がありま
   す。 配列には "Py_mod_abi" エントリーを含める必要があります。

   *spec* 引数には、"Py_mod_create" のドキュメントで説明する
   "ModuleSpec" に似たオブジェクトを使えます。 現在、*spec* には
   "name" 属性が必要です。

   成功すると新しいモジュールを返します。 エラー時には例外を設定して
   "NULL" を返します。

   この関数はモジュールの実行スロット ("Py_mod_exec") を処理しないこと
   に注意してください。 モジュールを完全に初期化するには、
   "PyModule_FromSlotsAndSpec()" と "PyModule_Exec()" の両方を呼び出す
   必要があります (多段階初期化 も参照)。

   Added in version 3.15.

int PyModule_Exec(PyObject *module)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   *module* の "Py_mod_exec" スロットを実行します。

   成功すると 0 を返します。 エラー時には例外を設定して -1 を返します
   。

   明確にすると、例えば 従来の一段階初期化 を使っていて *module* にス
   ロットがない場合、この関数は何もせずに 0 を返します。

   Added in version 3.15.


モジュール定義構造体
====================

従来、拡張モジュールは、その作成方法を「記述」する *モジュール定義* を
使って定義していました。 この定義は スロット の配列を直接使う代わりに
、よく使う機能専用のメンバーを持ち、拡張の仕組みとして追加のスロットを
指定できます。

このモジュール定義方法も引き続き利用でき、削除する予定はありません。

type PyModuleDef
    * 次に属します: Stable ABI (see below).*

   モジュールオブジェクトを作成するのに必要な情報を保持する、モジュー
   ル定義構造体です。

   この構造体は静的に割り当てる必要があります (または、この構造体から
   作成したモジュールが存在する間は有効であることを、別の方法で保証す
   る必要があります)。 通常、この方法で定義する拡張モジュールごとに、
   この型の変数を 1 つだけ用意します。

   この構造体は、すべてのメンバーを含め、フリースレッドでないビルドの
   安定 ABI ("abi3") の一部です。 フリースレッドビルドの安定 ABI
   ("abi3t") では、この構造体は不透明で実際には利用できません。 代替手
   段は モジュールの定義 を参照してください。

   PyModuleDef_Base m_base

      このメンバーは必ず "PyModuleDef_HEAD_INIT" で初期化してください:

      type PyModuleDef_Base
          * 次に属します: Stable ABI (see below).*

         "PyModuleDef.m_base" の型です。

         この構造体は、フリースレッドでないビルドの 安定 ABI ("abi3")
         の一部です。 フリースレッドビルドの安定 ABI ("abi3t") では、
         この構造体は不透明で実際には利用できません。

      PyModuleDef_HEAD_INIT

         "PyModuleDef.m_base" に必要な初期値です。

   const char *m_name

      "Py_mod_name" スロットに対応します。

   const char *m_doc

      これらのメンバーは "Py_mod_doc" スロットに対応します。 "NULL" を
      設定することは、スロットを省略することと等価です。

   Py_ssize_t m_size

      "Py_mod_state_size" スロットに対応します。 ゼロを設定することは
      、スロットを省略することと等価です。

      従来の一段階初期化 を使う場合や、"PyModule_Create()" または
      "PyModule_Create2()" でモジュールを動的に作成する場合は、
      "m_size" に -1 を設定できます。 これはモジュールがグローバルな状
      態を持つため、サブインタープリタに対応していないことを示します。

   PyMethodDef *m_methods

      "Py_mod_methods" スロットに対応します。 "NULL" を設定することは
      、スロットを省略することと等価です。

   PyModuleDef_Slot *m_slots

      "{0, NULL}" エントリーで終端された、追加のスロットの配列です。
      エントリーには "PySlot" ではなく、従来の "PyModuleDef_Slot" 構造
      体を使うことに注意してください。

      配列に "PyModuleDef" のメンバーに対応するスロットが含まれる場合
      、値は一致している必要があります。 例えば "m_slots" で
      "Py_mod_name" を使う場合、"PyModuleDef.m_name" には同じポインタ
      を設定する必要があります (等しい文字列というだけでは不十分です)
      。

      バージョン 3.5 で変更: バージョン 3.5 より前は、このメンバは常に
      "NULL" に設定されていて、次のものとして定義されていました:

         inquiry m_reload

      type PyModuleDef_Slot
          * 次に属します: Stable ABI (すべてのメンバーを含む) (バージ
         ョン 3.5 より).*

         モジュールの追加のスロットを定義する従来の構造体です。

         "Py_mod_slots" を使うと "PySlot" 配列に "PyModuleDef_Slot" 配
         列を含めることができ、逆方向は "Py_slot_subslots" で行えるこ
         とに注意してください。

         各 "PyModuleDef_Slot" 構造体 "modslot" は、次の "PySlot" 構造
         体として解釈されます。

            (PySlot){
               .sl_id=modslot.slot,
               .sl_flags=PySlot_INTPTR | sub_static,
               .sl_ptr=modslot.value
            }

         ここで "sub_static" は、そのスロットがフラグを必要とする場合
         ("Py_mod_methods" など)、または「親」の "Py_mod_slots" スロッ
         ト (存在する場合) にこのフラグがある場合は、"PySlot_STATIC"
         です。

         int slot

            "PySlot.sl_id" に対応します。

         void *value

            "PySlot.sl_ptr" に対応します。

         Added in version 3.5.

   traverseproc m_traverse
   inquiry m_clear
   freefunc m_free

      これらのメンバーは、それぞれ "Py_mod_state_traverse"、
      "Py_mod_state_clear"、"Py_mod_state_free" スロットに対応します。

      これらのメンバーに "NULL" を設定することは、対応するスロットを省
      略することと等価です。

      バージョン 3.9 で変更: モジュール状態の割り当て前には、
      "m_traverse"、"m_clear"、"m_free" 関数を呼び出さなくなりました。

PyTypeObject PyModuleDef_Type
    * 次に属します: Stable ABI (バージョン 3.5 より).*

   "PyModuleDef" オブジェクトの型です。

Py_mod_slots
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   "Py_slot_subslots" と同様に動作しますが、"PyModuleDef_Slot" 構造体
   の配列を指定する "スロット ID" です。

   Added in version 3.15.

次の API を使うと、"PyModuleDef" 構造体からモジュールを作成できます:

PyObject *PyModule_Create(PyModuleDef *def)
    *戻り値: 新しい参照。*

   *def* の定義から、新しいモジュールオブジェクトを作成します。 このマ
   クロは *module_api_version* に "PYTHON_API_VERSION" を設定して
   "PyModule_Create2()" を呼び出します。 制限付き API を使う場合は、代
   わりに "PYTHON_ABI_VERSION" を設定します。

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   APIバージョンを *module_api_version* として *def* での定義に従って
   新しいモジュールオブジェクトを生成します。 もし指定されたバージョン
   が実行しているインタープリターのバージョンと異なる場合は、
   "RuntimeWarning" を発生させます。

   エラー時には例外を設定して "NULL" を返します。

   この関数はスロットをサポートしません。 *def* の "m_slots" メンバー
   は "NULL" でなければなりません。

   注釈:

     ほとんどの場合、この関数ではなく "PyModule_Create()" を利用するべ
     きです。この関数は、この関数の必要性を理解しているときにだけ利用
     してください。

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
    *戻り値: 新しい参照。*

   このマクロは *module_api_version* に "PYTHON_API_VERSION" を設定し
   て "PyModule_FromDefAndSpec2()" を呼び出します。 制限付き API を使
   う場合は、代わりに "PYTHON_ABI_VERSION" を設定します。

   Added in version 3.5.

   バージョン 3.15 で ソフト非推奨 <Soft deprecated>: 新しいコードでは
   "PyModule_FromSlotsAndSpec()" を使うことを推奨します。

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.7
   より).*

   APIバージョンを *module_api_version* として、 *def* と ModuleSpec
   オブジェクトの *spec* で定義されたとおりに新しいモジュールオブジェ
   クトを生成します。 もし指定されたバージョンが実行しているインタープ
   リターのバージョンと異なる場合は、 "RuntimeWarning" を発生させます
   。

   エラー時には例外を設定して "NULL" を返します。

   この関数は実行スロット ("Py_mod_exec") を処理しないことに注意してく
   ださい。 モジュールを完全に初期化するには、
   "PyModule_FromDefAndSpec" と "PyModule_ExecDef" の両方を呼び出す必
   要があります。

   注釈:

     ほとんどの場合、この関数ではなく "PyModule_FromDefAndSpec()" を利
     用するべきです。 この関数は、この関数の必要性を理解しているときに
     だけ利用してください。

   Added in version 3.5.

   バージョン 3.15 で ソフト非推奨 <Soft deprecated>: 新しいコードでは
   "PyModule_FromSlotsAndSpec()" を使うことを推奨します。

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   *def* で与えられた任意の実行スロット ("Py_mod_exec") を実行します。

   Added in version 3.5.

   バージョン 3.15 で ソフト非推奨 <Soft deprecated>: モジュール自身の
   実行スロットを実行するには、"PyModule_Exec()" を使うことを推奨しま
   す。 この関数は "PyModuleDef" 構造体から作成していないモジュールに
   も使えます。

PYTHON_API_VERSION
PYTHON_API_STRING

   C API のバージョンを、それぞれ整数 ("1013") と文字列 (""1013"") で
   表したものです。 後方互換性のために定義されています。

   現在、新しい Python バージョンでもこの定数は更新されず、バージョン
   管理には役立ちません。 将来は変わる可能性があります。

PYTHON_ABI_VERSION
PYTHON_ABI_STRING

   後方互換性のため、それぞれ "3" と ""3"" として定義されています。

   現在、新しい Python バージョンでもこの定数は更新されず、バージョン
   管理には役立ちません。 将来は変わる可能性があります。


サポート関数
============

以下の関数は、モジュールオブジェクトの初期化を補助するために用意されて
います。 モジュールの実行スロット ("Py_mod_exec")、従来の 一段階初期化
の初期化関数、またはモジュールを動的に作成するコードで使うことを想定し
ています。

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)
    * 次に属します: Stable ABI (バージョン 3.10 より).*

   *module* にオブジェクトを *name* として追加します。 この関数はモジ
   ュールの初期化関数から利用される便利関数です。

   成功すると "0" を返し、エラーになると例外を送出して "-1" を返します
   。

   使用例:

      static int
      add_spam(PyObject *module, int value)
      {
          PyObject *obj = PyLong_FromLong(value);
          if (obj == NULL) {
              return -1;
          }
          int res = PyModule_AddObjectRef(module, "spam", obj);
          Py_DECREF(obj);
          return res;
       }

   使いやすいように、例外が設定されていれば *value* に "NULL" を受け付
   けます。 この場合は "-1" を返し、送出された例外はそのままにします。

   この例は、明示的に *obj* が "NULL" であることを確認せずに書くことも
   できます:

      static int
      add_spam(PyObject *module, int value)
      {
          PyObject *obj = PyLong_FromLong(value);
          int res = PyModule_AddObjectRef(module, "spam", obj);
          Py_XDECREF(obj);
          return res;
       }

   この場合は、 *obj* が "NULL" でありうるため、 "Py_DECREF()" の代わ
   りに "Py_XDECREF()" を呼び出す必要があることに注意してください。

   この関数に渡す *name* 文字列の種類は少数に抑える必要があります。 通
   常は *name* に静的に割り当てた文字列だけを使います。 コンパイル時に
   分からない名前には、"PyUnicode_FromString()" と
   "PyObject_SetAttr()" を直接呼び出すことを推奨します。 詳細は、キー
   オブジェクトの作成に内部で使われることがある
   "PyUnicode_InternFromString()" を参照してください。

   Added in version 3.10.

int PyModule_Add(PyObject *module, const char *name, PyObject *value)
    * 次に属します: Stable ABI (バージョン 3.13 より).*

   "PyModule_AddObjectRef()" と同様ですが、*value* への参照を (エラー
   時も)「*盗みます*」。 新しい参照を返す関数の結果を、確認したり変数
   に保存したりすることなく、そのまま渡して呼び出せます。

   使用例:

      if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
          goto error;
      }

   Added in version 3.13.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
    * 次に属します: Stable ABI.*

   "PyModule_AddObjectRef()" と同様ですが、成功時 ("0" を返した場合)
   に *value* への参照を *盗みます*。

   "PyModule_AddObject()" 関数は誤用により参照のリークを起こしやすいた
   め、新しい "PyModule_Add()" または "PyModule_AddObjectRef()" 関数を
   推奨します。

   注釈:

     参照を盗む他の関数とは異なり、"PyModule_AddObject()" が *value*
     への参照を解放するのは **成功時だけ** です。そのため、戻り値を確
     認する必要があり、エラー時には呼び出し側のコードが *value* に対し
     て明示的に "Py_XDECREF()" を行わなければなりません。

   使用例:

      PyObject *obj = PyBytes_FromString(value);
      if (PyModule_AddObject(module, "spam", obj) < 0) {
          // 'obj' が NULL でなく、PyModule_AddObject() が失敗した場合は、
          // Py_XDECREF() で 'obj' への強参照を解放する必要があります。
          // 'obj' が NULL の場合、Py_XDECREF() は何もしません。
          Py_XDECREF(obj);
          goto error;
      }
      // PyModule_AddObject() が obj への参照を盗んだため、
      // ここで Py_XDECREF(obj) は不要です。

   バージョン 3.13 で ソフト非推奨 <Soft deprecated>.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
    * 次に属します: Stable ABI.*

   整数定数を *name* として *module* に追加します。 この便利関数はモジ
   ュールの初期化関数から使えます。 エラー時には例外を設定して "-1"、
   成功すると "0" を返します。

   この便利関数は "PyLong_FromLong()" と "PyModule_AddObjectRef()" を
   呼び出します。 詳細はそれぞれのドキュメントを参照してください。

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
    * 次に属します: Stable ABI.*

   文字列定数を *name* として *module* に追加します。 この便利関数はモ
   ジュールの初期化関数から使えます。 文字列 *value* は "NULL" 終端さ
   れている必要があります。 エラー時には例外を設定して "-1"、成功する
   と "0" を返します。

   この便利関数は "PyUnicode_InternFromString()" と
   "PyModule_AddObjectRef()" を呼び出します。 詳細はそれぞれのドキュメ
   ントを参照してください。

PyModule_AddIntMacro(module, macro)

   整数定数を *module* に追加します。 名前と値は *macro* から取得しま
   す。 例えば "PyModule_AddIntMacro(module, AF_INET)" は、値が
   *AF_INET* の整数定数 *AF_INET* を *module* に追加します。 エラー時
   には例外を設定して "-1"、成功すると "0" を返します。

PyModule_AddStringMacro(module, macro)

   文字列定数を *module* に追加します。

int PyModule_AddType(PyObject *module, PyTypeObject *type)
    * 次に属します: Stable ABI (バージョン 3.10 より).*

   型オブジェクトを *module* に追加します。 内部で "PyType_Ready()" を
   呼び出して型オブジェクトの準備を完了します。 型オブジェクトの名前に
   は、"tp_name" の最後のドットの後の部分を使います。 エラー時には例外
   を設定して "-1"、成功すると "0" を返します。

   Added in version 3.9.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   "NULL" で終端された *functions* 配列の関数を *module* に追加します
   。 各エントリーの詳細は "PyMethodDef" のドキュメントを参照してくだ
   さい。 (C で実装するモジュールレベルの「関数」は、共有されるモジュ
   ール名前空間がないため、通常は最初の引数にモジュールを受け取ります
   。 そのため Python クラスのインスタンスメソッドに似ています。)

   この関数は "PyModuleDef" からモジュールを作成するとき (例えば 多段
   階初期化、"PyModule_Create"、"PyModule_FromDefAndSpec" を使うとき)
   に自動的に呼び出されます。 複数の "PyMethodDef" 配列に関数を定義し
   たい場合は、この関数を直接呼び出してください。

   *functions* 配列は静的に割り当てる必要があります (または、モジュー
   ルオブジェクトより長く存続することを別の方法で保証する必要がありま
   す)。

   Added in version 3.5.

int PyModule_SetDocString(PyObject *module, const char *docstring)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   *module* の docstring を *docstring* に設定します。 この関数は
   "PyModuleDef" からモジュールを作成するとき (例えば 多段階初期化、
   "PyModule_Create"、"PyModule_FromDefAndSpec" を使うとき) に自動的に
   呼び出されます。

   成功すると "0" を返します。 エラー時には例外を設定して "-1" を返し
   ます。

   Added in version 3.5.

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)

   *これは Unstable APIです。マイナーリリースで予告なく変更されること
   があります。*

   "Py_mod_gil" の値のいずれかを使って、*module* がグローバルインター
   プリタロック (GIL) なしでの実行に対応するかどうかを示します。 従来
   の一段階初期化 を使う場合、*module* の初期化関数の中で呼び出す必要
   があります。 モジュール初期化中にこの関数を呼び出さなければ、インポ
   ート機構はモジュールが GIL なしでの実行に対応していないとみなします
   。 この関数は "--disable-gil" を指定して構成した Python ビルドでの
   み利用できます。 エラー時には例外を設定して "-1"、成功すると "0" を
   返します。

   Added in version 3.13.


モジュールの検索 (一段階初期化)
-------------------------------

従来の 一段階初期化 方式は、現在のインタープリタのコンテキストで検索で
きるシングルトンのモジュールを作成します。 そのため、モジュール定義へ
の参照だけで、後からモジュールオブジェクトを取得できます。

多段階初期化を使うと単一の定義から複数のモジュールが作成できるので、こ
れらの関数は多段階初期化を使って作成されたモジュールには使えません。

PyObject *PyState_FindModule(PyModuleDef *def)
    *戻り値: 借用参照。** 次に属します: Stable ABI.*

   現在のインタプリタの *def* から作られたモジュールオブジェクトを返し
   ます。このメソッドの前提条件として、前もって "PyState_AddModule()"
   でインタプリタの state にモジュールオブジェクトを連結しておくことを
   要求します。対応するモジュールオブジェクトが見付からない、もしくは
   事前にインタプリタの state に連結されていない場合は、 "NULL" を返し
   ます。

int PyState_AddModule(PyObject *module, PyModuleDef *def)
    * 次に属します: Stable ABI (バージョン 3.3 より).*

   関数に渡されたモジュールオブジェクトを、インタプリタの state に連結
   します。この関数を使うことで "PyState_FindModule()" からモジュール
   オブジェクトにアクセスできるようになります。

   一段階初期化を使って作成されたモジュールにのみ有効です。

   Python は 一段階初期化 を使うモジュールのインポート後に、自動的に
   "PyState_AddModule" を呼び出します。 そのため、モジュール初期化コー
   ドから呼び出す必要はありません (呼び出しても問題はありません)。 明
   示的な呼び出しが必要なのは、モジュール自身の初期化コードが、その後
   で "PyState_FindModule" を呼び出す場合だけです。 この関数は主に、別
   のインポート機構の実装を想定しています (直接呼び出すことも、必要な
   状態更新の詳細を知るために実装を参照することもできます)。

   同じ *def* を使ってモジュールがすでに関連づけられていた場合は、新し
   い *module* に置き換えます。

   呼び出し側には *アタッチされたスレッド状態* が必要です。

   エラー時には例外を設定して "-1"、成功すると "0" を返します。

   Added in version 3.3.

int PyState_RemoveModule(PyModuleDef *def)
    * 次に属します: Stable ABI (バージョン 3.3 より).*

   *def* から作成されたモジュールオブジェクトを、インタープリタの状態
   から削除します。 エラー時には例外を設定して "-1"、成功すると "0" を
   返します。

   呼び出し側には *アタッチされたスレッド状態* が必要です。

   Added in version 3.3.
