:mod:`runpy` --- Python モジュールの位置特定と実行
==================================================

.. module:: runpy
   :synopsis: 先行インポートなしの Python モジュールの位置特定と実行。
.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>


.. versionadded:: 2.5

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

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

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

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


.. function:: 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__`` は自動的に :mod:`__builtin__` モジュールのトップレベル名前空間への参照で初期化されます。

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

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


.. seealso::

   :pep:`338` - Executing modules as scripts
      Nick Coghlan によって書かれ実装された PEP

