モジュールオブジェクト (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 のインスタンスでしか使えません。 特に以下のスロットが該当します:

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.