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

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

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

Availability: not WASI.

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

コマンドラインでの使用

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

directory ...
file ...

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

-l

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

-f

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

-q

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

-d destdir

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

-s strip_prefix
-p prepend_prefix

Remove (-s) or append (-p) the given prefix of paths recorded in the .pyc files. Cannot be combined with -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

Use N workers to compile the files within the given directory. If 0 is used, then the result of os.process_cpu_count() will be used.

--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

Compile with the given optimization level. May be used multiple times to compile for multiple levels at a time (for example, compileall -o 1 -o 2).

-e dir

Ignore symlinks pointing outside the given directory.

If two .pyc files with different optimization level have the same content, use hard links to consolidate duplicate files.

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

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

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

バージョン 3.9 で変更: Added the -s, -p, -e and --hardlink-dupes options. Raised the default recursion limit from 10 to sys.getrecursionlimit(). Added the possibility to specify the -o option multiple times.

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=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 が真の場合、タイムスタンプが最新のであってもモジュールは再コンパイルされます。

If rx is given, its search method is called on the complete path to each file considered for compilation, and if it returns a true value, the file is skipped. This can be used to exclude files matching a regular expression, given as a re.Pattern object.

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

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

optimize specifies the optimization level for the compiler. It is passed to the built-in compile() function. Accepts also a sequence of optimization levels which lead to multiple compilations of one .py file in one call.

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ファイルを実行時に無効化する方法を制御します。

The stripdir, prependdir and limit_sl_dest arguments correspond to the -s, -p and -e options described above. They may be specified as str or os.PathLike.

If hardlink_dupes is true and two .pyc files with different optimization level have the same content, use hard links to consolidate duplicate files.

バージョン 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 で変更: The invalidation_mode parameter's default value is updated to None.

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

バージョン 3.9 で変更: Added stripdir, prependdir, limit_sl_dest and hardlink_dupes arguments. Default value of maxlevels was changed from 10 to 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 が与えられた場合、コンパイルされるファイルのパスの先頭にそのディレクトリを追加します。これはコンパイル時トレースバックに使われ、バイトコードファイルが実行される時点でソースファイルが存在しない場合に、トレースバックやその他のメッセージに使われるバイトコードファイルにもコンパイルされます。

If rx is given, its search method is passed the full path name to the file being compiled, and if it returns a true value, the file is not compiled and True is returned. This can be used to exclude files matching a regular expression, given as a re.Pattern object.

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

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

optimize specifies the optimization level for the compiler. It is passed to the built-in compile() function. Accepts also a sequence of optimization levels which lead to multiple compilations of one .py file in one call.

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

The stripdir, prependdir and limit_sl_dest arguments correspond to the -s, -p and -e options described above. They may be specified as str or os.PathLike.

If hardlink_dupes is true and two .pyc files with different optimization level have the same content, use hard links to consolidate duplicate files.

Added in version 3.2.

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

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

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

バージョン 3.7.2 で変更: The invalidation_mode parameter's default value is updated to 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 で変更: The invalidation_mode parameter's default value is updated to 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

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