5.3 モジュールの import

PyObject* PyImport_ImportModule(char *name)
戻り値: 新たな参照.
この関数は下で述べる PyImport_ImportModuleEx() を単純化したインタフェースで、 globals および locals 引数を NULLのままにしたものです。 name 引数にドットが含まれる場合 (あるパッケージの サブモジュールを指定している場合)、fromlist 引数が リスト ['*'] に追加され、戻り値がモジュールを含む トップレベルパッケージではなく名前つきモジュール (named module) に なるようにします。 (残念ながらこのやり方には、name が実際にはサブモジュールでなく サブパッケージを指定している場合、パッケージの __all__ 変数に指定されている サブモジュールがロードされてしまうという副作用があります。) import されたモジュールへの新たな参照を返します。失敗した 場合には例外をセットし、NULL を返します。 Python 2.4 以前では、 失敗した場合でもモジュールは生成されていることがあります -- sys.modules を使って調べてください。 Python 2.4 以降では、 import に失敗した モジュールは sys.modules に残りません。

バージョン 2.4 で 変更 された仕様: import に失敗した場合、不完全なモジュールを除去するように なりました

PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
戻り値: 新たな参照.
モジュールを import します。モジュールの import については 組み込みの Python 関数__import__()を読むとよく分かります。というのも、標準の __import__() はこの関数を直接呼び出しているからです。

戻り値は import されたモジュールかトップレベルパッケージへの新たな参照 になります。失敗した場合には例外をセットし、NULL を返します (Python 2.4 よりも前のバージョンでは、モジュールは生成されている場合が あります) __import__() と同じく、パッケージに対してサブモジュール を要求した場合の戻り値は通常、空でない fromlist を指定しない 限りトップレベルパッケージになります。 バージョン 2.4 で 変更 された仕様: import に失敗した場合、不完全なモジュールを除去するように なりました

PyObject* PyImport_Import(PyObject *name)
戻り値: 新たな参照.
現在の ``import フック関数'' を呼び出すための高水準のインタフェース です。この関数は現在のグローバル変数辞書内の __builtins__ から __import__() 関数を呼び出します。 すなわち、現在の環境にインストールされている import フック、 例えば rexecihooks を使って import を行います。

PyObject* PyImport_ReloadModule(PyObject *m)
戻り値: 新たな参照.
モジュールを再ロード (reload) します。モジュールの再ロードについては 組み込みの Python 関数reload()を読むとよく分かります。というのも、標準の reload はこの関数を直接呼び出しているからです。 戻り値は再ロードしたモジュールかトップレベルパッケージへの新たな参照 になります。失敗した場合には例外をセットし、NULL を返します (その場合でも、モジュールは生成されている場合があります)

PyObject* PyImport_AddModule(char *name)
戻り値: 借りた参照.
モジュール名に対応するモジュールオブジェクトを返します。 name 引数は package.module の形式でもかまいません。 まずモジュール辞書に該当するモジュールがあるかどうか調べ、 なければ新たなモジュールを生成してモジュール辞書に挿入します。 失敗した場合には例外をセットして NULL を返します。 注意: この関数はモジュールの import やロードを行いません; モジュールがまだロードされていなければ、空のモジュール オブジェクトを得ることになります。 PyImport_ImportModule() やその別形式を使って モジュールを import してください。ドット名表記で 指定したname が存在しない場合、パッケージ構造は 作成されません。

PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
戻り値: 新たな参照.
モジュール名 (package.module 形式でもかまいません) および Python のバイトコードファイルや組み込み関数 compile() で得られたコードオブジェクトを元にモジュールを ロードします。 モジュールオブジェクトへの新たな参照を返します。失敗した 場合には例外をセットし、NULL を返します。Python 2.4 以前では、 失敗した場合でもモジュールは生成されていることがありました。 Python 2.4 以降では、たとえPyImport_ExecCodeModule() の処理に 入った時にnamesys.modules に入っていたとしても、 import に失敗したモジュールは sys.modules に残りません。 初期化の不完全なモジュールを sys.modules に残すのは危険 であり、そのようなモジュールを import するコードにとっては、モジュール の状態がわからない (モジュール作者の意図から外れた壊れた状態かもしれない) からです。

この関数は、すでに import されているモジュールの場合には再ロードを 行います。意図的にモジュールの再ロードを行う方法は PyImport_ReloadModule() を参照してください。

namepackage.module 形式のドット名表記で あった場合、まだ作成されていないパッケージ構造はその作成されない ままになります。

バージョン 2.4 で 変更 された仕様: エラーが発生した場合にnamesys.modules から除去するようになりました

long PyImport_GetMagicNumber()
Python バイトコードファイル (いわゆる .pyc および .pyo ファイル) のマジックナンバを返します。マジックナンバは バイトコードファイルの先頭 4 バイトにリトルエンディアン整列で 配置されています。

PyObject* PyImport_GetModuleDict()
戻り値: 借りた参照.
モジュール管理のための辞書 (いわゆる sys.modules )を返します。 この辞書はインタプリタごとに一つだけある変数なので注意してください。

void _PyImport_Init()
import 機構を初期化します。 内部使用だけのための関数です。

void PyImport_Cleanup()
モジュールテーブルを空にします。 内部使用だけのための関数です。

void _PyImport_Fini()
import 機構を終了処理します。 内部使用だけのための関数です。

PyObject* _PyImport_FindExtension(char *, char *)
戻り値: 借りた参照.
内部使用だけのための関数です。

PyObject* _PyImport_FixupExtension(char *, char *)
内部使用だけのための関数です。

int PyImport_ImportFrozenModule(char *name)
name という名前のフリーズ (freeze) されたモジュールをロード します。成功すると 1 を、モジュールが見つからなかった場合には 0 を、初期化が失敗した場合には例外をセットして-1 を 返します。ロードに成功したモジュールにアクセスするには PyImport_ImportModule() を使ってください。 (Note この関数名はいささか誤称めいています -- この関数は すでに import 済みのモジュールをリロードしてしまいます。)

struct _frozen
freeze ユーティリティが生成するような フリーズ化モジュールデスクリプタの構造体型定義です。 (Python ソース配布物の Tools/freeze/ を参照してください) この構造体の定義は Include/import.h にあり、以下のように なっています:

struct _frozen {
    char *name;
    unsigned char *code;
    int size;
};

struct _frozen* PyImport_FrozenModules
このポインタは struct _frozen のレコードからなり、 終端の要素のメンバが NULL かゼロになっているような配列 を指すよう初期化されます。フリーズされたモジュールを import する とき、このテーブルを検索します。サードパーティ製のコードから このポインタに仕掛けを講じて、動的に生成されたフリーズ化モジュールの 集合を提供するようにできます。

int PyImport_AppendInittab(char *name, void (*initfunc)(void))
既存の組み込みモジュールテーブルに単一のモジュールを追加します。 この関数は利便性を目的とした PyImport_ExtendInittab() のラッパ関数で、テーブルが拡張できないときには -1 を返します。 新たなモジュールは name で import でき、最初に import を 試みた際に呼び出される関数として initfunc を使います。 Py_Initialize() よりも前に呼び出さねばなりません。

struct _inittab
組み込みモジュールリスト内の一つのエントリを記述している構造体です。 リスト内の各構造体には、インタプリタ内に組み込まれているモジュールの 名前と初期化関数が指定されています。 Python を埋め込むようなプログラムは、この構造体の配列と PyImport_ExtendInittab() を組み合わせて、追加の 組み込みモジュールを提供できます。構造体はInclude/import.h で以下のように定義されています:

struct _inittab {
    char *name;
    void (*initfunc)(void);
};

int PyImport_ExtendInittab(struct _inittab *newtab)
組み込みモジュールのテーブルに一群のモジュールを追加します。 配列 newtabname フィールドが NULL になっている センチネル (sentinel) エントリで終端されていなければなりません; センチネル値を与えられなかった場合にはメモリ違反になるかもしれません。 成功すると 0 を、内部テーブルを拡張するのに十分なメモリを 確保できなかった場合には -1 を返します。操作が失敗した場合、 モジュールは一切内部テーブルに追加されません。 Py_Initialize() よりも前に呼び出さねばなりません。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。