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

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


.. versionadded:: 2.5

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

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

.. function:: 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* が :const:`None` でない場合、
   指定されたモジュールがパッケージであれば ``mod_name + '.__main__'`` に、
   そうでなければ *mod_name* 引数の値がセットされます。

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

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

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

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

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


   .. versionchanged:: 2.7
         Added ability to execute packages by looking for a ``__main__``
         submodule


.. function:: 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`` を元に :mod:`__main__` モジュールを
   検索して実行します。指定された場所に :mod:`__main__` モジュールが無かった時、
   ``sys.path`` のどこか他のエントリに存在する別の :mod:`__main__` を実行して
   しまう可能性があることに注意してください。

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

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

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

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

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

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

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

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

   .. versionadded:: 2.7

.. seealso::

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

   :pep:`366` - Main module explicit relative imports
      Nick Coghlan によって書かれ実装された PEP

   :ref:`using-on-general` - CPython コマンドライン詳細
