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

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

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

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

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは
、WebAssembly プラットフォーム を見てください。


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

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

directory ...
file ...

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

-l

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

-f

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

-q

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

-d destdir

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

-s strip_prefix

   ".pyc" ファイルに記録するパスから、指定された接頭辞を取り除きます。
   パスはその接頭辞からの相対パスになります。

   このオプションは "-p" と併用できますが、"-d" とは併用できません。

-p prepend_prefix

   ".pyc" ファイルに記録するパスの先頭に、指定された接頭辞を追加します
   。 パスを絶対パスにするには "-p /" を使ってください。

   このオプションは "-s" と併用できますが、"-d" とは併用できません。

-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.process_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" になります。

-o level

   指定された最適化レベルでコンパイルします。 複数回指定すると、複数の
   レベルで一度にコンパイルできます (例: "compileall -o 1 -o 2")。

-e dir

   指定されたディレクトリの外を指すシンボリックリンクを無視します。

--hardlink-dupes

   最適化レベルが異なる二つの ".pyc" ファイルの内容が同じ場合、ハード
   リンクを使って重複するファイルをまとめます。

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

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

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

バージョン 3.9 で変更: "-s"、"-p"、"-e"、"--hardlink-dupes" オプション
が追加されました。 デフォルトの再帰上限が 10 から
"sys.getrecursionlimit()" に引き上げられました。 "-o" オプションを複数
回指定できるようになりました。

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

同様に、"compile()" 関数は "sys.pycache_prefix" の設定に従います。 生
成されたバイトコードキャッシュを利用するには、"compile()" の実行時とコ
ードの実行時で "sys.pycache_prefix" の設定を揃える必要があります (設定
しない場合も同様です)。


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

compileall.compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

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

   *maxlevels* パラメータで最大再帰深度を制限します。デフォルトは
   "sys.getrecursionlimit()" です。

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

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

   *rx* が指定された場合、コンパイル対象の各ファイルの完全なパスを引数
   として、その "search" メソッドを呼び出します。 真の値が返された場合
   、そのファイルはスキップされます。 re.Pattern オブジェクトとして渡
   した正規表現にマッチするファイルを除外するために使えます。

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

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

   *optimize* はコンパイラの最適化レベルを指定します。 この値は組み込
   みの "compile()" 関数に渡されます。 最適化レベルのシーケンスも受け
   付け、その場合は一回の呼び出しで一つの ".py" ファイルを複数回コンパ
   イルします。

   *workers* 引数は、ファイルを並列にコンパイルするワーカーの数を指定
   します。 デフォルトでは複数のワーカーを使いません。 複数のワーカー
   を使えないプラットフォームで *workers* 引数が指定された場合は、逐次
   コンパイルにフォールバックします。 *workers* が 0 の場合は、システ
   ムのコア数が使われます。 *workers* が "0" より小さい場合は
   "ValueError" を送出します。

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

   *stripdir*、*prependdir*、*limit_sl_dest* 引数は、それぞれ上で説明
   した "-s"、"-p"、"-e" オプションに対応します。 "str" または
   "os.PathLike" として指定できます。

   *hardlink_dupes* が真で、最適化レベルが異なる二つの ".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 で変更: *workers* を 0 に設定すると、最適なコア数が
   選択されるようになりました。

   バージョン 3.9 で変更: *stripdir*、*prependdir*、*limit_sl_dest*、
   *hardlink_dupes* 引数が追加されました。 *maxlevels* のデフォルト値
   が "10" から "sys.getrecursionlimit()" に変更されました。

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

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

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

   *rx* が指定された場合、コンパイル対象のファイルの完全なパス名を、そ
   の "search" メソッドに渡します。 真の値が返された場合、そのファイル
   はコンパイルされず、"True" が返されます。 re.Pattern オブジェクトと
   して渡した正規表現にマッチするファイルを除外するために使えます。

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

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

   *optimize* はコンパイラの最適化レベルを指定します。 この値は組み込
   みの "compile()" 関数に渡されます。 最適化レベルのシーケンスも受け
   付け、その場合は一回の呼び出しで一つの ".py" ファイルを複数回コンパ
   イルします。

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

   *stripdir*、*prependdir*、*limit_sl_dest* 引数は、それぞれ上で説明
   した "-s"、"-p"、"-e" オプションに対応します。 "str" または
   "os.PathLike" として指定できます。

   *hardlink_dupes* が真で、最適化レベルが異なる二つの ".pyc" ファイル
   の内容が同じ場合、ハードリンクを使って重複するファイルをまとめます
   。

   Added in version 3.2.

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

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

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

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

   バージョン 3.9 で変更: 引数 *stripdir* 、 *prependdir* 、
   *limit_sl_dest* 、および *hardlink_dupes* を追加しました。

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)

   # .svn ディレクトリ内のファイルを除外して同じコンパイルを実行
   import re
   compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

   # pathlib.Path オブジェクトも使用可能
   import pathlib
   compileall.compile_dir(pathlib.Path('Lib/'), force=True)

参考:

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