モジュールのインポート

PyObject *PyImport_ImportModule(const char *name)

戻り値: 新しい参照。 次に属します: Stable ABI.

PyImport_Import() のラッパーで、引数として PyObject* の代わりに const char* を受け取ります。

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

戻り値: 新しい参照。

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

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

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

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

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.7 より).

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

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

Added in version 3.3.

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

戻り値: 新しい参照。 次に属します: Stable ABI.

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

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

PyObject *PyImport_Import(PyObject *name)

戻り値: 新しい参照。 次に属します: Stable ABI.

現在の「インポートフック関数」を呼び出す高水準のインターフェースです (level は明示的に 0、つまり絶対インポートに設定されます)。 現在のグローバル名前空間の __builtins__ から __import__() 関数を呼び出します。 したがって、現在の環境にインストールされたインポートフックを使ってインポートします。

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

PyObject *PyImport_ReloadModule(PyObject *m)

戻り値: 新しい参照。 次に属します: Stable ABI.

モジュールを再読み込みします。 再読み込みしたモジュールへの新しい参照を返します。 失敗した場合は例外を設定して NULL を返します (この場合もモジュールは存在します)。

PyObject *PyImport_AddModuleRef(const char *name)

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.13 より).

モジュール名に対応するモジュールオブジェクトを返します。

name 引数は package.module という形式でも構いません。 まずモジュール辞書内を確認し、該当するモジュールがなければ新しく作成してモジュール辞書に挿入します。

成功した場合はモジュールへの 強参照 を返します。 失敗した場合は例外を設定して NULL を返します。

モジュール名 name は UTF-8 からデコードされます。

この関数はモジュールを読み込んだりインポートしたりしません。 モジュールがまだ読み込まれていない場合は、空のモジュールオブジェクトが返されます。 モジュールをインポートするには PyImport_ImportModule() またはその変種を使ってください。 name がドットで区切られた名前であっても、まだ存在しないパッケージ構造は作成されません。

Added in version 3.13.

PyObject *PyImport_AddModuleObject(PyObject *name)

戻り値: 借用参照。 次に属します: Stable ABI (バージョン 3.7 より).

PyImport_AddModuleRef() と同様ですが、借用参照 を返し、name は Python の str オブジェクトです。

Added in version 3.3.

PyObject *PyImport_AddModule(const char *name)

戻り値: 借用参照。 次に属します: Stable ABI.

PyImport_AddModuleRef() と同様ですが、借用参照 を返します。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

モジュール名 (package.module 形式でも可) と、Python バイトコードファイルから読み込んだか組み込み関数 compile() で取得したコードオブジェクトを使って、モジュールを読み込みます。 モジュールオブジェクトへの新しい参照を返し、エラーの場合は例外を設定して NULL を返します。 エラーの場合、PyImport_ExecCodeModule() の呼び出し時に name がすでに sys.modules に存在していたとしても、sys.modules から name を削除します。 不完全に初期化されたモジュールを sys.modules に残すのは危険です。 そのモジュールをインポートする側には、モジュールオブジェクトが不明な状態 (おそらく作者の意図からすれば壊れた状態) にあると知る手段がないためです。

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

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

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

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

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

バージョン 3.12 で変更: __cached__ と __loader__ の設定は非推奨になりました。 代替については ModuleSpec を参照してください。

バージョン 3.15 で変更: __cached__ 属性を設定しなくなりました。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

PyImport_ExecCodeModule() と同様ですが、pathname が NULL でなければモジュールオブジェクトの __file__ 属性をその値に設定します。

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

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

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.7 より).

PyImport_ExecCodeModuleEx() と同様ですが、cpathname が NULL でなければ、そこで指定されたコンパイル済みファイルのパスを適切に使います。 三つの関数の中では、この関数の使用を推奨します。

Added in version 3.3.

バージョン 3.12 で変更: __cached__ の設定は非推奨になりました。 代替については ModuleSpec を参照してください。

バージョン 3.15 で変更: __cached__ 属性を設定しなくなりました。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

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

Added in version 3.2.

バージョン 3.3 で変更: バイトコードのパスだけが指定された場合、ソースのパスの計算に imp.source_from_cache() を使います。

バージョン 3.12 で変更: 削除された imp モジュールを使わなくなりました。

long PyImport_GetMagicNumber()

次に属します: Stable ABI.

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

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

const char *PyImport_GetMagicTag()

次に属します: Stable ABI.

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

Added in version 3.2.

PyObject *PyImport_GetModuleDict()

戻り値: 借用参照。 次に属します: Stable ABI.

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

PyObject *PyImport_GetModule(PyObject *name)

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.8 より).

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

Added in version 3.7.

PyObject *PyImport_GetImporter(PyObject *path)

戻り値: 新しい参照。 次に属します: Stable ABI.

sys.path または pkg.__path__ の要素 path に対応するファインダーオブジェクトを返します。 sys.path_importer_cache 辞書から取得する場合もあります。 まだキャッシュされていなければ、そのパス要素を扱えるフックが見つかるまで sys.path_hooks を順に調べます。 どのフックも扱えない場合は None を返し、パスベースのファインダー がこのパス要素のファインダーを見つけられなかったことを呼び出し側に伝えます。 結果は sys.path_importer_cache にキャッシュします。 ファインダーオブジェクトへの新しい参照を返します。

int PyImport_ImportFrozenModuleObject(PyObject *name)

次に属します: Stable ABI (バージョン 3.7 より).

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

Added in version 3.3.

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

int PyImport_ImportFrozenModule(const char *name)

次に属します: Stable ABI.

PyImport_ImportFrozenModuleObject() と同様ですが、名前は Unicode オブジェクトではなく UTF-8 エンコードの文字列です。

struct _frozen

freeze ユーティリティ (Python ソース配布物の Tools/freeze/ を参照) が生成する、フリーズされたモジュールの記述子の構造体型です。 Include/import.h にある定義は次のとおりです。

struct _frozen {
    const char *name;                 /* ASCII エンコードの文字列 */
    const unsigned char *code;
    int size;
    int is_package;
};

バージョン 3.11 で変更: 新しい is_package フィールドは、モジュールがパッケージかどうかを示します。 size フィールドを負の値に設定する方法に代わるものです。

const struct _frozen *PyImport_FrozenModules

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

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

次に属します: Stable ABI.

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

struct _inittab

組み込みモジュールの一覧の一つのエントリーを記述する構造体です。 Python を組み込むプログラムは、この構造体の配列を PyImport_ExtendInittab() と併用して、追加の組み込みモジュールを提供できます。 構造体は二つのメンバからなります。

const char *name

ASCII エンコードの文字列で表したモジュール名。

PyObject *(*initfunc)(void)

インタープリタに組み込まれたモジュールの初期化関数。

inittab は「PyInit」の 初期化関数 を使います。 現在、「PyModExport_」の エクスポートフック を含める方法はありません。

int PyImport_ExtendInittab(struct _inittab *newtab)

組み込みモジュールのテーブルに、複数のモジュールを追加します。 newtab 配列は、name フィールドが NULL の番兵エントリーで終わる必要があります。 番兵がないとメモリアクセス違反を引き起こす可能性があります。 成功した場合は 0 を返し、内部テーブルを拡張するためのメモリを十分に割り当てられなければ -1 を返します。 失敗した場合、内部テーブルにモジュールは一つも追加されません。 Py_Initialize() より前に呼び出す必要があります。

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

struct _inittab *PyImport_Inittab

Python の初期化で使う組み込みモジュールのテーブルです。 直接使わず、代わりに PyImport_AppendInittab() と PyImport_ExtendInittab() を使ってください。

PyObject *PyImport_ImportModuleAttr(PyObject *mod_name, PyObject *attr_name)

戻り値: 新しい参照。

モジュール mod_name をインポートし、その属性 attr_name を取得します。

名前は Python の str オブジェクトでなければなりません。

PyImport_Import() と PyObject_GetAttr() を組み合わせた補助関数です。 例えば、モジュールが見つからなければ ImportError、属性が存在しなければ AttributeError を送出することがあります。

Added in version 3.14.

PyObject *PyImport_ImportModuleAttrString(const char *mod_name, const char *attr_name)

戻り値: 新しい参照。

PyImport_ImportModuleAttr() と同様ですが、名前は Python の str オブジェクトではなく UTF-8 エンコードの文字列です。

Added in version 3.14.

PyImport_LazyImportsMode PyImport_GetLazyImportsMode()

現在の遅延インポートモードを取得します。

Added in version 3.15.

PyObject *PyImport_GetLazyImportsFilter()

現在の遅延インポートフィルタへの 強参照 を返します。 フィルタがなければ NULL を返します。 この関数は常に成功します。

Added in version 3.15.

int PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)

現在の遅延インポートモードを設定します。

この関数は常に 0 を返します。

Added in version 3.15.

int PyImport_SetLazyImportsFilter(PyObject *filter)

現在の遅延インポートフィルタを設定します。 filter には、インポートを遅延できる可能性があるときに (importing_module_name, imported_module_name, [fromlist]) を受け取る呼び出し可能オブジェクトを指定してください。 imported_module_name は解決済みのモジュール名なので、lazy from .spam import eggs の場合は package.spam が渡されます。 この呼び出し可能オブジェクトは、インポートを遅延すべきなら True、そうでなければ False を返す必要があります。

成功した場合は 0 を返し、それ以外の場合は例外を設定して -1 を返します。

Added in version 3.15.

type PyImport_LazyImportsMode

遅延インポートモードの列挙型。

enumerator PyImport_LAZY_NORMAL

ソースコード内の lazy キーワードに従います。 デフォルトのモードです。

enumerator PyImport_LAZY_ALL

デフォルトですべてのインポートを遅延させます。

Added in version 3.15.

PyObject *PyImport_CreateModuleFromInitfunc(PyObject *spec, PyObject *(*initfunc)(void))

この関数は、Python を組み込む側が、静的拡張 (例えば静的リンクされた拡張) 用のカスタムインポータの create_module() ステップを実装するための構成要素です。

spec は ModuleSpec オブジェクトでなければなりません。

initfunc は、PyImport_AppendInittab() と同じく 初期化関数 でなければなりません。

成功した場合は、モジュールオブジェクトを作成して返します。 このモジュールはまだ初期化されていないので、PyModule_Exec() を呼び出して初期化してください。 (カスタムインポータでは exec_module() メソッド内で行ってください。)

エラーの場合は例外を設定して NULL を返します。

従来の単相初期化 を使うモジュールでは、通常インポータが create_module() の後で行う追加のステップではなく、この関数内でインポート処理の大半を行います。 具体的には次のとおりです。

• 初期化の一環として、モジュールを spec の name の名前で sys.modules に追加します。

• 同じ name の単相モジュールが、この関数または組み込みモジュールとして (例えば PyImport_AppendInittab() で登録して) 以前にインポートされていた場合、Python は initfunc を再び呼ぶ代わりに、以前のモジュールの内容を再利用することがあります。

• モジュールは initfunc によって完全に初期化されます。 PyModule_Exec() を呼び出しても効果はありませんが、モジュールが将来 多相初期化 に移行した場合に備えて、呼び出すことを推奨します。

• また、spec の name にドットが含まれる場合、この名前を使って新しいモジュールの __name__ に親パッケージの名前を前置します。

Added in version 3.15.