"compileall" --- Byte-compile Python libraries
**********************************************

**ソースコード:** 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 ...

   Positional arguments are files to compile or directories that
   contain source files, traversed recursively.  If no argument is
   given, behave as if the command line was "-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"
     一つのソースファイルをバイトコンパイルします。
