モジュールのインポート¶
-
PyObject *
PyImport_ImportModule
(const char *name)¶ - Return value: New reference. Part of the Stable ABI.
この関数は下で述べる
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. Part of the Stable ABI.
この関数は、
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. Part of the Stable ABI since version 3.7.
モジュールをインポートします。モジュールのインポートについては組み込みの 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. Part of the Stable ABI.
PyImport_ImportModuleLevelObject()
と似ていますが、name が Unicode オブジェクトではなく UTF-8 でエンコードされた文字列である点で異なります。バージョン 3.3 で変更: level にはもはや負の値は使用できません。
-
PyObject *
PyImport_Import
(PyObject *name)¶ - Return value: New reference. Part of the Stable ABI.
現在の "インポートフック関数" を呼び出すための高水準のインターフェースです (level に 0 を明示すると、絶対インポートを意味します)。 この関数は現在のグローバル変数辞書内の
__builtins__
から__import__()
関数を呼び出します。すなわち、現在の環境にインストールされているインポートフック使ってインポートを行います。この関数は常に絶対インポートを使用します。
-
PyObject *
PyImport_ReloadModule
(PyObject *m)¶ - Return value: New reference. Part of the Stable ABI.
モジュールを再ロード (reload) します。戻り値は再ロードしたモジュールかトップレベルパッケージへの新たな参照になります。 失敗した場合には例外をセットし、
NULL
を返します (その場合でも、モジュールは生成されている場合があります)。
-
PyObject *
PyImport_AddModuleObject
(PyObject *name)¶ - Return value: Borrowed reference. Part of the Stable ABI since version 3.7.
モジュール名に対応するモジュールオブジェクトを返します。name 引数は
package.module
の形式でもかまいません。 まずモジュール辞書に該当するモジュールがあるかどうか調べ、なければ新たなモジュールを生成してモジュール辞書に挿入します。 失敗した場合には例外をセットしてNULL
を返します。注釈
この関数はモジュールのインポートやロードを行いません; モジュールがまだロードされていなければ、空のモジュールオブジェクトを得ることになります。
PyImport_ImportModule()
やその別形式を使ってモジュールをインポートしてください。ドット名表記で指定した name が存在しない場合、パッケージ構造は作成されません。バージョン 3.3 で追加.
-
PyObject *
PyImport_AddModule
(const char *name)¶ - Return value: Borrowed reference. Part of the Stable ABI.
PyImport_AddModuleObject()
と似ていますが、name が UTF-8 でエンコードされた文字列ではなく Unicode オブジェクトを使用する点で異なります。
-
PyObject *
PyImport_ExecCodeModule
(const char *name, PyObject *co)¶ - Return value: New reference. Part of the Stable ABI.
モジュール名 (
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. Part of the Stable ABI.
PyImport_ExecCodeModule()
と似ていますが、pathname がNULL
でない場合にモジュールオブジェクトの__file__
属性に pathname が設定される点が異なります。PyImport_ExecCodeModuleWithPathnames()
も参照してください。
-
PyObject *
PyImport_ExecCodeModuleObject
(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)¶ - Return value: New reference. Part of the Stable ABI since version 3.7.
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. Part of the Stable ABI.
PyImport_ExecCodeModuleObject()
と似ていますが、 name と pathname、 cpathname が UTF-8 でエンコードされた文字列である点が異なります。もし pathname がNULL
の場合、cpathname から、pathname どのような値になるべきかを知る試みもなされます。バージョン 3.2 で追加.
バージョン 3.3 で変更: バイトコードのパスが与えられた場合にのみ
imp.source_from_cache()
がソースパスの計算に使用されます。
-
long
PyImport_GetMagicNumber
()¶ - Part of the Stable ABI.
Python バイトコードファイル (別名
.pyc
ファイル) のマジックナンバーを返します。マジックナンバーはバイトコードファイルの最初の4バイトに、リトルエンディアンバイトオーダーで現れるべきです。エラーの場合は-1
を返します。バージョン 3.3 で変更: 失敗した場合は
-1
の値を返します。
-
const char *
PyImport_GetMagicTag
()¶ - Part of the Stable ABI.
マジックタグ文字列を Python バイトコードファイル名の PEP 3147 フォーマットで返します。
sys.implementation.cache_tag
の値が信頼でき、かつこの関数の代わりに使用すべきであることを肝に命じましょう。バージョン 3.2 で追加.
-
PyObject *
PyImport_GetModuleDict
()¶ - Return value: Borrowed reference. Part of the Stable ABI.
モジュール管理のための辞書 (いわゆる
sys.modules
)を返します。この辞書はインタプリタごとに一つだけある変数なので注意してください。
-
PyObject *
PyImport_GetModule
(PyObject *name)¶ - Return value: New reference. Part of the Stable ABI since version 3.8.
与えられた名前の既にインポート済みのモジュールを返します。 モジュールがインポートされていなかった場合は、
NULL
を返しますが、エラーはセットしません。 モジュールの検索に失敗した場合は、NULL
を返し、エラーをセットします。バージョン 3.7 で追加.
-
PyObject *
PyImport_GetImporter
(PyObject *path)¶ - Return value: New reference. Part of the Stable ABI.
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)¶ - Part of the Stable ABI since version 3.7.
name という名前のフリーズ (freeze) されたモジュールをロードします。成功すると
1
を、モジュールが見つからなかった場合には0
を、初期化が失敗した場合には例外をセットして-1
を返します。ロードに成功したモジュールにアクセスするにはPyImport_ImportModule()
を使ってください。 (Note この関数はいささか誤解を招く名前です --- この関数はモジュールがすでにインポートされていたらリロードしてしまいます。)バージョン 3.3 で追加.
バージョン 3.4 で変更:
__file__
属性はもうモジュールにセットされません。
-
int
PyImport_ImportFrozenModule
(const char *name)¶ - Part of the Stable ABI.
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
¶ このポインタは
_frozen
のレコードからなり、終端の要素のメンバがNULL
かゼロになっているような配列を指すよう初期化されます。 フリーズされたモジュールをインポートするとき、このテーブルを検索します。 サードパーティ製のコードからこのポインタに仕掛けを講じて、動的に生成されたフリーズ化モジュールの集合を提供するようにできます。
-
int
PyImport_AppendInittab
(const char *name, PyObject *(*initfunc)(void))¶ - Part of the Stable ABI.
既存の組み込みモジュールテーブルに単一のモジュールを追加します。この関数は利便性を目的とした
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()
は、それぞれの初期化の前に呼び出される必要があります。