モジュールオブジェクト (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__ 属性を設定してモジュール名を変更できることに注意してください。

void *PyModule_GetState(PyObject *module)

次に属します: Stable ABI.

Return the "state" of the module, that is, a pointer to the block of memory allocated at module creation time, or NULL. See PyModuleDef.m_size.

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() を使用してください。

Module definitions

The functions in the previous section work on any module object, including modules imported from Python code.

Modules defined using the C API typically use a module definition, PyModuleDef -- a statically allocated, constant “description" of how a module should be created.

The definition is usually used to define an extension's “main” module object (see 拡張モジュールの定義 for details). It is also used to create extension modules dynamically.

Unlike PyModule_New(), the definition allows management of module state -- a piece of memory that is allocated and cleared together with the module object. Unlike the module's Python attributes, Python code cannot replace or delete data stored in module state.

type PyModuleDef

次に属します: Stable ABI (すべてのメンバーを含む).

The module definition struct, which holds all information needed to create a module object. This structure must be statically allocated (or be otherwise guaranteed to be valid while any modules created from it exist). Usually, there is only one variable of this type for each extension module.

PyModuleDef_Base m_base

Always initialize this member to PyModuleDef_HEAD_INIT.

const char *m_name

Name for the new module.

const char *m_doc

Docstring for the module; usually a docstring variable created with PyDoc_STRVAR is used.

Py_ssize_t m_size

Module state may be kept in a per-module memory area that can be retrieved with PyModule_GetState(), rather than in static globals. This makes modules safe for use in multiple sub-interpreters.

This memory area is allocated based on m_size on module creation, and freed when the module object is deallocated, after the m_free function has been called, if present.

Setting it to a non-negative value means that the module can be re-initialized and specifies the additional amount of memory it requires for its state.

Setting m_size to -1 means that the module does not support sub-interpreters, because it has global state. Negative m_size is only allowed when using legacy single-phase initialization or when creating modules dynamically.

詳細は PEP 3121 を参照。

PyMethodDef *m_methods

A pointer to a table of module-level functions, described by PyMethodDef values. Can be NULL if no functions are present.

PyModuleDef_Slot *m_slots

An array of slot definitions for multi-phase initialization, terminated by a {0, NULL} entry. When using legacy single-phase initialization, m_slots must be NULL.

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

inquiry m_reload

traverseproc m_traverse

A traversal function to call during GC traversal of the module object, or NULL if not needed.

This function is not called if the module state was requested but is not allocated yet. This is the case immediately after the module is created and before the module is executed (Py_mod_exec function). More precisely, this function is not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

バージョン 3.9 で変更: No longer called before the module state is allocated.

inquiry m_clear

A clear function to call during GC clearing of the module object, or NULL if not needed.

This function is not called if the module state was requested but is not allocated yet. This is the case immediately after the module is created and before the module is executed (Py_mod_exec function). More precisely, this function is not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

Like PyTypeObject.tp_clear, this function is not always called before a module is deallocated. For example, when reference counting is enough to determine that an object is no longer used, the cyclic garbage collector is not involved and m_free is called directly.

バージョン 3.9 で変更: No longer called before the module state is allocated.

freefunc m_free

A function to call during deallocation of the module object, or NULL if not needed.

This function is not called if the module state was requested but is not allocated yet. This is the case immediately after the module is created and before the module is executed (Py_mod_exec function). More precisely, this function is not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

バージョン 3.9 で変更: No longer called before the module state is allocated.

PyTypeObject PyModuleDef_Type

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

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

Module slots

type PyModuleDef_Slot

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

int slot

A slot ID, chosen from the available values explained below.

void *value

Value of the slot, whose meaning depends on the slot ID.

Added in version 3.5.

The available slot types are:

Py_mod_create

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

Specifies a function that is called to create the module object itself. The value pointer of this slot must point to a function of the signature:

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

The function receives a ModuleSpec instance, as defined in PEP 451, and the module definition. It should return a new module object, or set an error and return NULL.

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

Multiple Py_mod_create slots may not be specified in one module definition.

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

There is no requirement for the returned object to be an instance of PyModule_Type. Any type can be used, as long as it supports setting and getting import-related attributes. However, only PyModule_Type instances may be returned if the PyModuleDef has non-NULL m_traverse, m_clear, m_free; non-zero m_size; or slots other than Py_mod_create.

Added in version 3.5.

Py_mod_exec

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

Specifies a function that is called to execute the module. This is equivalent to executing the code of a Python module: typically, this function adds classes and constants to the module. The signature of the function is:

int exec_module(PyObject *module)

If multiple Py_mod_exec slots are specified, they are processed in the order they appear in the m_slots array.

Added in version 3.5.

Py_mod_multiple_interpreters

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

Specifies one of the following values:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED

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

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

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

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

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

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

Multiple Py_mod_multiple_interpreters slots may not be specified in one module definition.

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

Added in version 3.12.

Py_mod_gil

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

Specifies one of the following values:

Py_MOD_GIL_USED

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

Py_MOD_GIL_NOT_USED

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

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

Multiple Py_mod_gil slots may not be specified in one module definition.

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

Added in version 3.13.

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

The following functions may be used to create a module outside of an extension's initialization function. They are also used in single-phase initialization.

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.

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.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)

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

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

Added in version 3.5.

PYTHON_API_VERSION

The C API version. Defined for backwards compatibility.

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

PYTHON_ABI_VERSION

Defined as 3 for backwards compatibility.

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

サポート関数

The following functions are provided to help initialize a module state. They are intended for a module's execution slots (Py_mod_exec), the initialization function for legacy single-phase initialization, or code that creates modules dynamically.

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.