# 5 `runpy` -- Python モジュールの位置特定と実行

バージョン 2.5 で 新たに追加 された仕様です。

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

スクリプトとして実行されると、このモジュールは効率よく以下の操作をします。

        del sys.argv[0]  # Remove the runpy module from the arguments
        run_module(sys.argv[0], run_name="__main__", alter_sys=True)

`runpy` モジュールでは一つの関数だけ提供します。

`run_module`( | mod_name[, init_globals] [, run_name][, alter_sys])

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

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

  特別なグローバル変数 `__name__`、`__file__`、`__loader__`、 `__builtins__` はモジュールコードが実行される前にグローバル辞書にセットされます。

  `__name__` は、もしオプション引数 run_name が与えられていればその値が、 そうでなければ mod_name 引数の値がセットされます。

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

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

  `__builtins__` は自動的に `__builtin__` モジュールのトップレベル 名前空間への参照で初期化されます。

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

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

参考:

PEP 338, Executing modules as scripts
  Nick Coghlan によって書かれ実装された PEP