モジュールのインポート

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

This is a simplified interface to PyImport_ImportModuleEx() below, leaving the globals and locals arguments set to NULL and level set to 0. When the name argument contains a dot (when it specifies a submodule of a package), the fromlist argument is set to the list ['*'] so that the return value is the named module rather than the top-level package containing it as would otherwise be the case. (Unfortunately, this has an additional side effect when name in fact specifies a subpackage instead of a submodule: the submodules specified in the package's __all__ variable are loaded.) Return a new reference to the imported module, or NULL with an exception set on failure. A failing import of a module doesn't leave the module in 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__() を読むとよくわかります。

The return value is a new reference to the imported module or top-level package, or NULL with an exception set on failure. Like for __import__(), the return value when a submodule of a package was requested is normally the top-level package, unless a non-empty fromlist was given.

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

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

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

The return value is a new reference to the imported module or top-level package, or NULL with an exception set on failure. Like for __import__(), the return value when a submodule of a package was requested is normally the top-level package, unless a non-empty fromlist was given.

バージョン 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 a module. Return a new reference to the reloaded module, or NULL with an exception set on failure (the module still exists in this case).

PyObject* PyImport_AddModuleObject(PyObject *name)
Return value: Borrowed reference.

Return the module object corresponding to a module name. The name argument may be of the form package.module. First check the modules dictionary if there's one there, and if not, create a new one and insert it in the modules dictionary. Return NULL with an exception set on failure.

注釈

この関数はモジュールのインポートやロードを行いません; モジュールがまだロードされていなければ、空のモジュールオブジェクトを得ることになります。 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.

Given a module name (possibly of the form package.module) and a code object read from a Python bytecode file or obtained from the built-in function compile(), load the module. Return a new reference to the module object, or NULL with an exception set if an error occurred. name is removed from sys.modules in error cases, even if name was already in sys.modules on entry to PyImport_ExecCodeModule(). Leaving incompletely initialized modules in sys.modules is dangerous, as imports of such modules have no way to know that the module object is an unknown (and probably damaged with respect to the module author's intents) state.

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

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

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

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

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

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

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

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

PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
Return value: New reference.

PyImport_ExecCodeModuleEx() と似ていますが、cpathnameNULL でない場合にモジュールオブジェクトの __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() と似ていますが、 namepathnamecpathname が UTF-8 でエンコードされた文字列である点が異なります。もし pathnameNULL の場合、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.

Return the already imported module with the given name. If the module has not been imported yet then returns NULL but does not set an error. Returns NULL and sets an error if the lookup failed.

バージョン 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 へキャッシュし、オブジェクトへの新たな参照を返します。

void _PyImport_Init()

インポート機構を初期化します。内部使用だけのための関数です。

void PyImport_Cleanup()

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

void _PyImport_Fini()

インポート機構を終了処理します。内部使用だけのための関数です。

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

This pointer is initialized to point to an array of struct _frozen records, terminated by one whose members are all NULL or zero. When a frozen module is imported, it is searched in this table. Third-party code could play tricks with this to provide a dynamically created collection of frozen modules.

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)

Add a collection of modules to the table of built-in modules. The newtab array must end with a sentinel entry which contains NULL for the name field; failure to provide the sentinel value can result in a memory fault. Returns 0 on success or -1 if insufficient memory could be allocated to extend the internal table. In the event of failure, no modules are added to the internal table. This should be called before Py_Initialize().