31.7. runpy --- Python モジュールの位置特定と実行

バージョン 2.5 で追加.

ソースコード: Lib/runpy.py

runpy モジュールは Python のモジュールをインポートせずにその位置を特定したり実行したりするのに使われます。その主な目的はファイルシステムではなく Python のモジュール名前空間を使って位置を特定したスクリプトの実行を可能にする -m コマンドラインスイッチを実装することです。

runpy モジュールは2つの関数を提供しています:

runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)

指定されたモジュールのコードを実行し、実行後のモジュールグローバル辞書を返します。モジュールのコードはまず標準インポート機構(詳細は PEP 302 を参照) を使ってモジュールの位置を特定され、まっさらなモジュール名前空間で実行されます。

指定されたモジュール名が通常のモジュールではなくパッケージを参照していた場合、そのパッケージが import された後その中の __main__ モジュールが実行され、実行後のモジュールグローバル辞書を返します。

オプションの辞書型引数 init_globals はコードを実行する前にモジュールグローバル辞書に前もって必要な設定しておくのに使われます。与えられた辞書は変更されません。その辞書の中に以下に挙げる特別なグローバル変数が定義されていたとしても、それらの定義は run_module() 関数によってオーバーライドされます。

特別なグローバル変数 __name__, __file__, __loader__, __package__ はモジュールコードが実行される前にグローバル辞書にセットされます (この変数群は修正される最小セットです。これ以外の変数もインタプリタの実装の詳細として暗黙的に設定されるかもしれません)。

__name__ は、オプション引数 run_name が None でない場合、指定されたモジュールがパッケージであれば mod_name + '.__main__' に、そうでなければ mod_name 引数の値がセットされます。

__file__ はモジュールローダにより与えられた名前がセットされます。もしローダがファイル名情報を取得可能にしなければ、この変数の値は None になります。

__loader__ はモジュールのコードを取得するのに使われる PEP 302 のモジュールローダがセットされます(このローダは標準のインポート機構に対するラッパーかもしれません)。

__package__ は指定されたモジュールがパッケージだった場合は mod_name に、それ以外の場合は mod_name.rpartition('.')[0] に設定されます。

引数 alter_sys が与えられて True に評価されるならば、 sys.argv[0] は __file__ の値で更新され sys.modules[__name__] は実行されるモジュールの一時的モジュールオブジェクトで更新されます。 sys.argv[0] と sys.modules[__name__] はどちらも関数が処理を戻す前にもとの値に復旧します。

この sys に対する操作はスレッドセーフではないということに注意してください。他のスレッドは部分的に初期化されたモジュールを見たり、入れ替えられた引数リストを見たりするかもしれません。この関数をスレッド化されたコードから起動するときは sys モジュールには手を触れないことが推奨されます。

参考

コマンドラインから、 -m オプションを与えることで同じ機能を実現出来ます。

バージョン 2.7 で変更: __main__ サブモジュールを検索することによってパッケージを実行する機能が追加されました。

runpy.run_path(file_path, init_globals=None, run_name=None)

指定されたファイルシステム上の場所にあるコードを実行して、結果としてそのモジュールグローバル辞書を返します。通常の CPython 実行時にコマンドラインで指定するスクリプト名と同じく、指定できるパスは Python ソースファイル、コンパイルされたバイトコードファイル、もしくは __main__ モジュールを含む有効な sys.path エントリ(例: トップレベルに __main__.py ファイルを持つ zip ファイル)です。

シンプルなスクリプトを指定した場合は、指定されたコードはシンプルに新しいモジュール名前空間で実行されます。有効な sys.path エントリ (一般的には zip ファイルかディレクトリ) を指定した場合は、最初にそのエントリが sys.path の先頭に追加されます。次に更新した sys.path を元に __main__ モジュールを検索して実行します。指定された場所に __main__ モジュールが無かった時、 sys.path のどこか他のエントリに存在する別の __main__ を実行してしまう可能性があることに注意してください。

オプションの辞書型引数 init_globals はコードを実行する前にモジュールグローバル辞書に前もって必要な設定しておくのに使われます。与えられた辞書は変更されません。その辞書の中に以下に挙げる特別なグローバル変数が定義されていたとしても、それらの定義は run_path() 関数によってオーバーライドされます。

特別なグローバル変数 __name__, __file__, __loader__, __package__ はモジュールコードが実行される前にグローバル辞書にセットされます (この変数群は修正される最小セットです。これ以外の変数もインタプリタの実装の詳細として暗黙的に設定されるかもしれません)。

__name__ は、オプション引数 run_name が None でない場合、 run_name に設定され、それ以外の場合は '<run_path>' に設定されます。

__file__ はモジュールローダにより与えられた名前がセットされます。もしローダがファイル名情報を取得可能にしなければ、この変数の値は None になります。シンプルなスクリプトの場合、これは file_path になるでしょう。

__loader__ はモジュールのコードを取得するのに使われる PEP 302 のモジュールローダがセットされます(このローダは標準のインポート機構に対するラッパーかもしれません)。シンプルなスクリプトの場合、これは None になるでしょう。

__package__ は __name__.rpartition('.')[0] に設定されます。

sys モジュールに対していくつかの変更操作が行われます。まず、 sys.path が上記のように修正されます。 sys.argv[0] は file_path に更新され、 sys.modules[__name__] は実行されるモジュールのための一時モジュールオブジェクトに更新されます。 sys の要素に対する全ての変更は、この関数から戻る前に元に戻されます。

run_module() と違い、 sys に対する変更はオプションではありません。これらの変更は sys.path エントリの実行に必要不可欠だからです。スレッドセーフ性に関する制限はこの関数にも存在します。この関数をマルチスレッドプログラムから実行する場合は、 import lock によりシリアライズして実行するか、別プロセスに委譲してください。

参考

コマンドラインから インターフェイスオプション で同じ機能を使えます (python path/to/script)。

バージョン 2.7 で追加.

参考

PEP 338 - モジュールをスクリプトとして実行する

Nick Coghlan によって書かれ実装された PEP。

PEP 366 - main モジュールの明示的な相対インポート

Nick Coghlan によって書かれ実装された PEP。

コマンドラインと環境 - CPython コマンドライン詳細