モジュールのインポート

PyObject* PyImport_ImportModule(const char *name)

Return value: New reference.

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

この関数は常に絶対インポートを使用します。

PyObject* PyImport_ImportModuleNoBlock(const char *name)

Return value: New reference.

この関数は、 PyImport_ImportModule() の廃止予定のエイリアスです。

バージョン 3.3 で変更: この関数は、従来は別のスレッドによってインポートロックが行われていた場合は即座に失敗していました。しかし Python 3.3 では、大部分の目的でロックスキームがモジュールごとのロックに移行したので、この関数の特別な振る舞いはもはや必要ではありません。

PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)

Return value: New reference.

モジュールをインポートします。モジュールのインポートについては組み込みの Python 関数 __import__() を読むとよくわかります。

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

インポートが失敗した場合は、PyImport_ImportModule() と同様に不完全なモジュールのオブジェクトを削除します。

PyObject* PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

Return value: New reference.

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

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

バージョン 3.3 で追加.

PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

Return value: New reference.

PyImport_ImportModuleLevelObject() と似ていますが、name が Unicode オブジェクトではなく UTF-8 でエンコードされた文字列である点で異なります。

バージョン 3.3 で変更: level にはもはや負の値は使用できません。

PyObject* PyImport_Import(PyObject *name)

Return value: New reference.

現在の "インポートフック関数" を呼び出すための高水準のインターフェースです (level に 0 を明示すると、絶対インポートを意味します)。 この関数は現在のグローバル変数辞書内の __builtins__ から __import__() 関数を呼び出します。すなわち、現在の環境にインストールされているインポートフック使ってインポートを行います。

この関数は常に絶対インポートを使用します。

PyObject* PyImport_ReloadModule(PyObject *m)

Return value: New reference.

モジュールを再ロード (reload) します。戻り値は再ロードしたモジュールかトップレベルパッケージへの新たな参照になります。 失敗した場合には例外をセットし、NULL を返します (その場合でも、モジュールは生成されている場合があります)。

PyObject* PyImport_AddModuleObject(PyObject *name)

Return value: Borrowed reference.

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

注釈

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

バージョン 3.3 で追加.

PyObject* PyImport_AddModule(const char *name)

Return value: Borrowed reference.

PyImport_AddModuleObject() と似ていますが、name が UTF-8 でエンコードされた文字列ではなく Unicode オブジェクトを使用する点で異なります。

PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)

Return value: New reference.

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

モジュールの __spec__ と __loader__ がまだ設定されていなければ、適切な値が設定されます。spec の ローダーは、モジュールの __loader__ が (もし設定されていれば) それに設定され、そうでなければ SourceFileLoader のインスタンスに設定されます。

モジュールの __file__ 属性はコードオブジェクトの co_filename へ設定されます。もし適切な場合は、 __cached__ へも設定されます。

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

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

PyImport_ExecCodeModuleEx() と PyImport_ExecCodeModuleWithPathnames() も参照してください。

PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)

Return value: New reference.

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

PyImport_ExecCodeModuleWithPathnames() も参照してください。

PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)

Return value: New reference.

PyImport_ExecCodeModuleEx() と似ていますが、cpathname が NULL でない場合にモジュールオブジェクトの __cached__ 属性に cpathname が設定される点が異なります。これらの 3 つの関数のうち、この関数の使用が望ましいです。

バージョン 3.3 で追加.

PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)

Return value: New reference.

PyImport_ExecCodeModuleObject() と似ていますが、 name と pathname、 cpathname が UTF-8 でエンコードされた文字列である点が異なります。もし pathname が NULL の場合、cpathname から、pathname どのような値になるべきかを知る試みもなされます。

バージョン 3.2 で追加.

バージョン 3.3 で変更: バイトコードのパスが与えられた場合にのみ imp.source_from_cache() がソースパスの計算に使用されます。

long PyImport_GetMagicNumber()

Python バイトコードファイル (別名 .pyc ファイル) のマジックナンバーを返します。マジックナンバーはバイトコードファイルの最初の4バイトに、リトルエンディアンバイトオーダーで現れるべきです。エラーの場合は -1 を返します。

バージョン 3.3 で変更: 失敗した場合は -1 の値を返します。

const char * PyImport_GetMagicTag()

マジックタグ文字列を Python バイトコードファイル名の PEP 3147 フォーマットで返します。sys.implementation.cache_tag の値が信頼でき、かつこの関数の代わりに使用すべきであることを肝に命じましょう。

バージョン 3.2 で追加.

PyObject* PyImport_GetModuleDict()

Return value: Borrowed reference.

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

PyObject* PyImport_GetModule(PyObject *name)

Return value: New reference.

与えられた名前の既にインポート済みのモジュールを返します。 モジュールがインポートされていなかった場合は、 NULL を返しますが、エラーはセットしません。 モジュールの検索に失敗した場合は、 NULL を返し、エラーをセットします。

バージョン 3.7 で追加.

PyObject* PyImport_GetImporter(PyObject *path)

Return value: New reference.

sys.path もしくは pkg.__path__ の要素である path を見付けるためのオブジェクトを返します。場合によっては sys.path_importer_cache 辞書から取得することもあります。 もしまだオブジェクトがキャッシュされていなかった場合は、 path 要素を扱えるフックが見付かるまで sys.path_hooks を走査します。 どのフックも path 要素を扱えない場合は None を返します; これにより、 path based finder がこの path 要素を見付けるためのオブジェクトが得られなかったことを呼び出し元に伝えます。 最終的に得られたオブジェクトを sys.path_importer_cache へキャッシュし、オブジェクトへの新たな参照を返します。

int PyImport_ImportFrozenModuleObject(PyObject *name)

Return value: New reference.

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

バージョン 3.3 で追加.

バージョン 3.4 で変更: __file__ 属性はもうモジュールにセットされません。

int PyImport_ImportFrozenModule(const char *name)

PyImport_ImportFrozenModuleObject() と似ていますが、name は UTF-8 でエンコードされた文字列の代わりに、 Unicode オブジェクトを使用する点が異なります。

struct _frozen

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

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

const struct _frozen* PyImport_FrozenModules

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

int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void))

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

struct _inittab

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

struct _inittab {
    const char *name;           /* ASCII encoded string */
    PyObject* (*initfunc)(void);
};

int PyImport_ExtendInittab(struct _inittab *newtab)

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

Python が複数回初期化される場合、PyImport_AppendInittab() または PyImport_ExtendInittab() は、それぞれの初期化の前に呼び出される必要があります。