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

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

======================================================================

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

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms
"wasm32-emscripten" and "wasm32-wasi". See WebAssembly プラットフォー
ム for more information.


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

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

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