:mod:`compileall` --- Python ライブラリをバイトコンパイル
=========================================================

.. module:: compileall
   :synopsis: ディレクトリに含まれる Python ソースファイルを、一括してバイトコンパイルします。


このモジュールは、Python ライブラリのインストールを助けるユーティリティ関数群を
提供します。この関数群は、ディレクトリツリー内の Python ソースファイルを
コンパイルします。このモジュールを使って、キャッシュされたバイトコードファイルを
ライブラリのインストール時に生成することで、ライブラリディレクトリに
書き込み権限をもたないユーザでも、これらを利用できるようになります。


コマンドラインでの使用
----------------------

このモジュールは、 (:program:`python -m compileall` を使って) Python ソースを
コンパイルするスクリプトとして機能します。

.. program:: compileall

.. cmdoption:: [directory|file]...

   位置引数は、コンパイルするファイル群か、再帰的に横断されるディレクトリで
   ソースファイル群を含むものです。引数が与えられなければ、
   ``-l <directories from sys.path>`` を渡したのと同じように動作します。

.. cmdoption:: -l

   サブディレクトリを再帰処理せず、指名または暗示されたディレクトリ群に含まれる
   ソースコードファイル群だけをコンパイルします。

.. cmdoption:: -f

   タイムスタンプが最新であってもリビルドを強制します。

.. cmdoption:: -q

   コンパイルされたファイルを一覧表示せず、エラーメッセージのみ表示します。

.. cmdoption:: -d destdir

   コンパイルされるそれぞれのファイルへのパスの先頭に、
   ディレクトリを追加します。これはコンパイル時トレースバックに使われ、
   バイトコードファイルが実行される時点でソースファイルが存在しない場合に、
   トレースバックやその他のメッセージに使われるバイトコードファイルにも
   コンパイルされます。

.. cmdoption:: -x regex

   regex を使って、コンパイル候補のそれぞれのファイルのフルパスを検索し、
   regex がマッチしたファイルを除外します。

.. cmdoption:: -i list

   ファイル ``list`` を読み込み、そのファイルのそれぞれの行を、
   コンパイルするファイルとディレクトリのリストに加えます。
   ``list`` が ``-`` なら、 ``stdin`` の行を読み込みます。

.. versionchanged:: 2.7
   ``-i`` オプションを追加しました。


パブリックな関数
----------------

.. function:: compile_dir(dir[, maxlevels[, ddir[, force[, rx[, quiet]]]]])

   *dir* で指定されたディレクトリを再帰的に下降し、見つかった :file:`.py` を
   全てコンパイルします。
   
   *maxlevels* パラメタは、再帰する深さの限度に使われ、デフォルトは
   ``10`` です。
   
   *ddir* が与えられれば、コンパイルされるそれぞれのファイルへのパスの先頭に、
   そのディレクトリを追加します。これはコンパイル時トレースバックに使われ、
   バイトコードファイルが実行される時点でソースファイルが存在しない場合に、
   トレースバックやその他のメッセージに使われるバイトコードファイルにも
   コンパイルされます。
   
   *force* が真の場合、モジュールはファイルの更新日付に関わりなく再コンパイルされます。

   *rx* が与えられれば、コンパイル候補のそれぞれのファイルのフルパスに対して
   検索メソッドが呼び出され、それが真値を返したら、そのファイルは除外されます。

   *quiet* が真の場合、エラーが起こらない限り標準出力に何も表示しません。


.. function:: compile_file(fullname[, ddir[, force[, rx[, quiet]]]])

   パス *fullname* のファイルをコンパイルします。

   *ddir* が与えられれば、コンパイルされるファイルへのパスの先頭に、
   そのディレクトリを追加します。これはコンパイル時トレースバックに使われ、
   バイトコードファイルが実行される時点でソースファイルが存在しない場合に、
   トレースバックやその他のメッセージに使われるバイトコードファイルにも
   コンパイルされます。

   *rx* が与えられれば、コンパイル候補のファイルのフルパスに対して
   検索メソッドが呼び出され、それが真値を返したら、
   ファイルはコンパイルされず、 ``True`` が返されます。

   *quiet* が真の場合、エラーが起こらない限り標準出力に何も表示しません。

   .. versionadded:: 2.7


.. function:: compile_path([skip_curdir[, maxlevels[, force]]])

   ``sys.path`` に含まれる、全ての :file:`.py` ファイルをバイトコンパイルします。
   *skip_curdir* が真（デフォルト）の時、カレントディレクトリは検索されません。
   その他のパラメタはすべて :func:`compile_dir` 関数に渡されます。
   なお、他のコンパイル関数とは違い、 *maxlevels* のデフォルトは ``0`` です。

:file:`Lib/` ディレクトリ以下にある全ての :file:`.py` ファイルを強制的に再コンパイルするには、以下のようにします::

   import compileall

   compileall.compile_dir('Lib/', force=True)

   # .svn ディレクトリにあるファイルを除いて同じことをするにはこのようにします。
   import re
   compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True)


.. seealso::

   :mod:`py_compile` モジュール
      一つのソースファイルをバイトコンパイルします。

