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 一つのソースファイルをバイトコンパイルします。