モジュールのインポート

PyObject *PyImport_ImportModule(const char *name)

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

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

PyObject *PyImport_ImportModuleNoBlock(const char *name)

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

This function is a deprecated alias of PyImport_ImportModule().

バージョン 3.3 で変更: This function used to fail immediately when the import lock was held by another thread. In Python 3.3 though, the locking scheme switched to per-module locks for most purposes, so this function's special behaviour isn't needed anymore.

バージョン 3.13 で非推奨、バージョン 3.15 で削除予定: Use PyImport_ImportModule() instead.

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 のインスタンスを設定します。

The module's __file__ attribute will be set to the code object's co_filename. If applicable, __cached__ will also be set.

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

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

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

バージョン 3.12 で変更: The setting of __cached__ and __loader__ is deprecated. See ModuleSpec for alternatives.

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 より).

Like PyImport_ExecCodeModuleEx(), but the __cached__ attribute of the module object is set to cpathname if it is non-NULL. Of the three functions, this is the preferred one to use.

Added in version 3.3.

バージョン 3.12 で変更: Setting __cached__ is deprecated. See ModuleSpec for alternatives.

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

This is the structure type definition for frozen module descriptors, as generated by the freeze utility (see Tools/freeze/ in the Python source distribution). Its definition, found in Include/import.h, is:

struct _frozen {
    const char *name;                 /* ASCII encoded string */
    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)

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

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.