"compileall" --- Python ライブラリをバイトコンパイル
****************************************************

**ソースコード:** Lib/compileall.py

======================================================================

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


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

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

directory ...
file ...

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

-l

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

-f

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

-q

   コンパイルされたファイルのリストを出力しません。 一つ渡された場合で
   もエラーメッセージは出力されます。 二つ ("-qq") の場合全ての出力は
   抑制されます。

-d destdir

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

-x regex

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

-i list

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

-b

   バイトコードファイルを、他のバージョンの Python によって生成された
   バイトコードファイルを上書きするかもしれない、レガシーな場所に生成
   します。デフォルトでは **PEP 3147** で決められた場所と名前を使い、
   複数のバージョンの Python が共存できるようにします。

-r

   サブディレクトリの最大再起深度を制御します。 このオプションが与えら
   れた場合、"-l" オプションは無視されます。 **python -m compileall
   <directory> -r 0** は **python -m compileall <directory> -l** と等
   価です。

-j N

   与えられたディレクトリ内のファイルを *N* ワーカでコンパイルします。
   "0" の場合 "os.cpu_count()" の結果が使用されます。

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

   生成したバイトコードファイルを実行時に無効化する方法を制御します。
   "timestamp" を指定すると、生成した``.pyc`` ファイルにソースファイル
   のタイムスタンプとサイズを埋め込みます。"checked-hash" と
   "unchecked-hash" を指定すると、ハッシュベースの pycファイルが生成さ
   れます。ハッシュベースのpycファイルは、ソースファイルにタイムスタン
   プではなくハッシュ値を埋め込みます。Python がバイトコードキャッシュ
   ファイルを実行時に検証する方法の詳細を知るには、キャッシュされたバ
   イトコードの無効化 を参照してください。デフォルト値は、
   "SOURCE_DATE_EPOCH" 環境変数が設定されていなければ "timestamp" で、
   "SOURCE_DATE_EPOCH" 環境変数が設定されていれば、"checked-hash" にな
   ります。

バージョン 3.2 で変更: "-i", "-b", "-h" オプションを追加。

バージョン 3.5 で変更: "-j", "-r", "-qq" オプションが追加されました。
"-q" オプションが複数のレベルの値に変更されました。"-b" は常に拡張子
".pyc" のバイトエンコーディングファイルを生成し、".pyo" を作りません。

バージョン 3.7 で変更: "--invalidation-mode" オプションが追加されまし
た。

"compile()" 関数で利用される最適化レベルを制御するコマンドラインオプシ
ョンはありません。 Python インタプリタ自体のオプションを使ってください
: **python -O -m compileall**.

Similarly, the "compile()" function respects the "sys.pycache_prefix"
setting. The generated bytecode cache will only be useful if
"compile()" is run with the same "sys.pycache_prefix" (if any) that
will be used at runtime.


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

compileall.compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None)

   *dir* という名前のディレクトリーツリーをたどり、途中で見つけた全て
   の ".py" をコンパイルします。全ファイルのコンパイルが成功した場合は
   真を、それ以外の場合は偽を返します。

   *maxlevels* 引数で最大再帰深度を制限します。デフォルトは "10" です
   。

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

   *force* が真の場合、タイムスタンプが最新のであってもモジュールは再
   コンパイルされます。

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

   *quiet* が "False" か "0" (デフォルト) の場合、ファイル名とその他の
   情報は標準出力に表示されます。 "1" の場合エラーのみが表示されます。
   "2" の場合出力はすべて抑制されます。

   *legacy* が真の時、バイトコードファイルは古い場所と名前に書かれ、他
   のバージョンの Python によって作られたバイトコードファイルを上書き
   する可能性があります。デフォルトは **PEP 3147** で決められた場所と
   名前を使い、複数のバージョンの Python のバイトコードファイルが共存
   できるようにします。

   *optimize* でコンパイラの最適化レベルを指定します。これは組み込みの
   "compile()" 関数に渡されます。

   The argument *workers* specifies how many workers are used to
   compile files in parallel. The default is to not use multiple
   workers. If the platform can't use multiple workers and *workers*
   argument is given, then sequential compilation will be used as a
   fallback.  If *workers* is 0, the number of cores in the system is
   used.  If *workers* is lower than "0", a "ValueError" will be
   raised.

   *invalidation_mode* は、"py_compile.PycInvalidationMode" のメンバー
   でなければならず、生成されたpycファイルを実行時に無効化する方法を制
   御します。

   バージョン 3.2 で変更: *legacy* と *optimize* 引数が追加されました
   。

   バージョン 3.5 で変更: "workers" パラメータが追加されました。

   バージョン 3.5 で変更: *quiet* 引数が複数のレベルの値に変更されまし
   た。

   バージョン 3.5 で変更: *optimize* の値に関わらず、*legacy* 引数は
   ".pyc" ファイルのみを書き出し、".pyo" ファイルを書き出さないように
   なりました。

   バージョン 3.6 で変更: *path-like object* を受け取るようになりまし
   た。

   バージョン 3.7 で変更: *invalidation_mode* 引数を追加しました。

   バージョン 3.7.2 で変更: *invalidation_mode* 引数のデフォルト値が
   None に変更されました。

   バージョン 3.8 で変更: Setting *workers* to 0 now chooses the
   optimal number of cores.

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

   パス *fullname* のファイルをコンパイルします。コンパイルが成功すれ
   ば真を、そうでなければ偽を返します。

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

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

   *quiet* が "False" か "0" (デフォルト) の場合、ファイル名とその他の
   情報は標準出力に表示されます。 "1" の場合エラーのみが表示されます。
   "2" の場合出力はすべて抑制されます。

   *legacy* が真の時、バイトコードファイルは古い場所と名前に書かれ、他
   のバージョンの Python によって作られたバイトコードファイルを上書き
   する可能性があります。デフォルトは **PEP 3147** で決められた場所と
   名前を使い、複数のバージョンの Python のバイトコードファイルが共存
   できるようにします。

   *optimize* でコンパイラの最適化レベルを指定します。これは組み込みの
   "compile()" 関数に渡されます。

   *invalidation_mode* は、"py_compile.PycInvalidationMode" のメンバー
   でなければならず、生成されたpycファイルを実行時に無効化する方法を制
   御します。

   バージョン 3.2 で追加.

   バージョン 3.5 で変更: *quiet* 引数が複数のレベルの値に変更されまし
   た。

   バージョン 3.5 で変更: *optimize* の値に関わらず、*legacy* 引数は
   ".pyc" ファイルのみを書き出し、".pyo" ファイルを書き出さないように
   なりました。

   バージョン 3.7 で変更: *invalidation_mode* 引数を追加しました。

   バージョン 3.7.2 で変更: *invalidation_mode* 引数のデフォルト値が
   None に変更されました。

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

   "sys.path" からたどって見つけたすべての ".py" ファイルをバイトコン
   パイルします。 すべてのファイルを問題なくコンパイルできたときに真を
   、それ以外のときに偽を返します。

   *skip_curdir* が真(デフォルト)のとき、カレントディレクトリは走査か
   ら除外されます。 それ以外のすべての引数は "compile_dir()" 関数に渡
   されます。 その他の compile 関数群と異なり、 "maxlevels" のデフォル
   トが "0" になっていることに注意してください。

   バージョン 3.2 で変更: *legacy* と *optimize* 引数が追加されました
   。

   バージョン 3.5 で変更: *quiet* 引数が複数のレベルの値に変更されまし
   た。

   バージョン 3.5 で変更: *optimize* の値に関わらず、*legacy* 引数は
   ".pyc" ファイルのみを書き出し、".pyo" ファイルを書き出さないように
   なりました。

   バージョン 3.7 で変更: *invalidation_mode* 引数を追加しました。

   バージョン 3.7.2 で変更: *invalidation_mode* 引数のデフォルト値が
   None に変更されました。

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

   import compileall

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

   # Perform same compilation, excluding files in .svn directories.
   import re
   compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

   # pathlib.Path objects can also be used.
   import pathlib
   compileall.compile_dir(pathlib.Path('Lib/'), force=True)

参考:

  Module "py_compile"
     一つのソースファイルをバイトコンパイルします。
