5.3 モジュールの import

PyObject* PyImport_ImportModule( const 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 フック、例えば rexec や ihooks を使って import を行います。

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

PyObject* PyImport_AddModule( const 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() の処理に入った時にname が sys.modules に入っていたとしても、 import に失敗したモジュールは sys.modules に残りません。初期化の不完全なモジュールを sys.modules に残すのは危険であり、そのようなモジュールを import するコードにとっては、モジュールの状態がわからない (モジュール作者の意図から外れた壊れた状態かもしれない) からです。

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

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

バージョン 2.4 で変更された仕様: エラーが発生した場合にname をsys.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): 組み込みモジュールのテーブルに一群のモジュールを追加します。配列 newtab は name フィールドが NULL になっているセンチネル (sentinel) エントリで終端されていなければなりません; センチネル値を与えられなかった場合にはメモリ違反になるかもしれません。成功すると 0 を、内部テーブルを拡張するのに十分なメモリを確保できなかった場合には -1 を返します。操作が失敗した場合、モジュールは一切内部テーブルに追加されません。 Py_Initialize() よりも前に呼び出さねばなりません。

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