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

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