モジュールのインポート

PyObject* PyImport_ImportModule(const char *name)
Return value: New reference.

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

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

バージョン 2.6 で変更: 常に、絶対 import を使うようになりました。

PyObject* PyImport_ImportModuleNoBlock(const char *name)

このバージョンの PyImport_ImportModule() はブロックしません。関数を実行するために他のモジュールをインポートするC関数から使われることを意図しています。インポート処理は他のスレッドがインポートロックを持っている場合はブロックします。この関数はブロックしません。まず sys.modules からモジュールのフェッチを試み、失敗したら、ロックが取られていなければ PyImport_ImportModule() を実行します。ロックが取られていた場合は ImportError を発生させます。

バージョン 2.6 で追加.

PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
Return value: New reference.

モジュールを import します。モジュールの import については組み込みの Python 関数 __import__() を読むとよく分かります。というのも、標準の __import__() はこの関数を直接呼び出しているからです。

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

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

バージョン 2.6 で変更: この関数は PyImport_ImportModuleLevel() のエイリアスです。 level には相対インポートを意味する -1 が渡されます。

PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
Return value: New reference.

モジュールを import します。モジュールの import については組み込みの Python 関数 __import__() を読むとよく分かります。というのも、標準の __import__() はこの関数を直接呼び出しているからです。

戻り値は、インポートされたモジュールかトップレベルパッケージへの新しい参照か、失敗した場合は例外を設定して NULL を返します。 __import__() と同じように、パッケージのサブモジュールが要求されたときは、空でない fromlist を渡された時以外は、トップレベルのパッケージを返します。

バージョン 2.5 で追加.

PyObject* PyImport_Import(PyObject *name)
Return value: New reference.

現在の "import フック関数" を呼び出すための高水準のインタフェースです。この関数は現在のグローバル変数辞書内の __builtins__ から __import__() 関数を呼び出します。すなわち、現在の環境にインストールされている import フック、例えば rexec や ihooks を使って import を行います。

バージョン 2.6 で変更: 常に、絶対 import を使うようになりました。

PyObject* PyImport_ReloadModule(PyObject *m)
Return value: New reference.

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

PyObject* PyImport_AddModule(const char *name)
Return value: Borrowed reference.

モジュール名に対応するモジュールオブジェクトを返します。name 引数は package.module の形式でもかまいません。まずモジュール辞書に該当するモジュールがあるかどうか調べ、なければ新たなモジュールを生成してモジュール辞書に挿入します。失敗した場合には例外をセットして NULL を返します。

注釈

この関数はモジュールの import やロードを行いません; モジュールがまだロードされていなければ、空のモジュールオブジェクトを得ることになります。 PyImport_ImportModule() やその別形式を使ってモジュールを import してください。ドット名表記で指定した name が存在しない場合、パッケージ構造は作成されません。

PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
Return value: New reference.

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

モジュールの __file__ 属性が、コードオブジェクトの co_filename に設定されます。

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

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

バージョン 2.4 で変更: エラーが発生した場合に name を sys.modules から除去するようになりました。

PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)
Return value: New reference.

PyImport_ExecCodeModule() と似ていますが、pathname が NULL でない場合にモジュールオブジェクトの __file__ 属性に pathname が設定される点が異なります。

long PyImport_GetMagicNumber()

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

PyObject* PyImport_GetModuleDict()
Return value: Borrowed reference.

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

PyObject* PyImport_GetImporter(PyObject *path)

sys.path/pkg.__path__ の要素 path の、 importer オブジェクトを返します。可能なら、 sys.path_importer_cache からフェッチします。まだキャッシュされていない場合、そのパスを扱える hook が見つかるまで sys.path_hooks を巡回します。 hook が見つからない場合、 None を返します。この場合、呼び出し元はビルトインのインポート機構にフォールバックします。結果は sys.path_importer_cache にキャッシュされます。 importer オブジェクトへの新しい参照を返します。

バージョン 2.6 で追加.

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(const 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() よりも前に呼び出さなければなりません。