32.11. compileall — Python ライブラリをバイトコンパイル

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

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

32.11.1. コマンドラインでの使用

このモジュールは、 (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() の結果が使用されます。

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

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

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

32.11.2. パブリックな関数

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

dir で指定されたディレクトリを再帰的に下降し、見つかった .py を全てコンパイルします。

maxlevels パラメタは、再帰する深さの限度に使われ、デフォルトは 10 です。

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

force が真の場合、モジュールはファイルの更新日付に関わりなく再コンパイルされます。

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

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

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

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

引数 workers でファイルを並列でコンパイルするワーカの数を指定します。デフォルトでは複数のワーカを使いません。 複数のワーカを使えないプラットフォームで workers が与えられた場合、逐次コンパイルにフォールバックします。workers が 0 未満の場合 ValueError を送出します。

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

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

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

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

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

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

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

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

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

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

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

バージョン 3.2 で追加.

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

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

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

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

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

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

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

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)

参考

Module py_compile

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