# `compileall` --- Python ライブラリをバイトコンパイル

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

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

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

このモジュールは、 (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`

  与えられたディレクトリ内のファイルを 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` になります。

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

`--hardlink-dupes```

  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`, `bytes` 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 で変更: invalidation_mode 引数のデフォルト値が 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`, `bytes` 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 で追加.

  バージョン 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)

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

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