"py_compile" --- Python ソースファイルをコンパイルする
******************************************************

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

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

"py_compile" モジュールは、ソースファイルからバイトコードファイルを生
成する関数と、モジュールのソースファイルをスクリプトとして実行したとき
に使う関数を提供します。

頻繁に必要となるわけではありませんが、複数のユーザーが共用するモジュー
ルをインストールする場合、、特にソースコードのあるディレクトリにバイト
コードのキャッシュファイルを書き込む権限がないユーザがいるときには、こ
の関数は役に立ちます。

exception py_compile.PyCompileError

   ファイルをコンパイル中にエラーが発生すると送出される例外。

py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)

   ソースファイルをバイトコードにコンパイルし、バイトコードキャッシュ
   ファイルを書き出します。 ソースコードは *file* で指定したファイルか
   ら読み込みます。 バイトコードは *cfile* に書き込まれます。 そのデフ
   ォルトは **PEP 3147**/**PEP 488** に従う、".pyc" で終わるパスです。
   例えば Python 3.2 では、*file* が "/foo/bar/baz.py" の場合、*cfile*
   のデフォルトは "/foo/bar/__pycache__/baz.cpython-32.pyc" になります
   。 *dfile* を指定すると、例外のトレースバックに表示するソース行を取
   得するファイル名として、*file* の代わりに使われます。 *doraise* が
   真の場合、*file* のコンパイル中にエラーが発生すると
   "PyCompileError" が送出されます。 *doraise* が偽 (デフォルト) の場
   合、エラー文字列を "sys.stderr" に書き出しますが、例外は送出しませ
   ん。 この関数はバイトコンパイルされたファイルへのパス、つまり実際に
   使われた *cfile* の値を返します。

   *doraise* 引数と *quiet* 引数は、ファイルのコンパイル中のエラーの扱
   いを決めます。 *quiet* が 0 または 1 で *doraise* が偽の場合は、デ
   フォルトの動作になります。 エラー文字列を "sys.stderr" に書き出し、
   パスの代わりに "None" を返します。 *doraise* が真の場合は、代わりに
   "PyCompileError" を送出します。 ただし *quiet* が 2 の場合、メッセ
   ージは書き出されず、*doraise* は効果を持ちません。

   (明示的に指定されたか計算された結果の) *cfile* のパスがシンボリック
   リンクだったり通常のファイルでなかったりした場合は、
   "FileExistsError" が送出されます。この動作は、それらのパスにバイト
   コンパイルされたファイルを書き込む権限がある場合、インポートのとき
   にそのパスを通常のファイルに変えてしまうことを警告するためのもので
   す。これはリネームを使ってバイトコンパイルされたファイルを配置する
   インポートで、同時にファイル書き込みをしてしまう問題を避けるための
   副作用です。

   *optimize* は最適化レベルを制御するもので、組み込みの "compile()"
   関数に渡されます。デフォルトは現在のインタープリタの最適化レベルを
   選ぶ "-1" です。

   *invalidation_mode* には "PycInvalidationMode" 列挙型のメンバーを指
   定します。 生成したバイトコードキャッシュを実行時に無効化する方法を
   制御します。 環境変数 "SOURCE_DATE_EPOCH" が設定されている場合、デ
   フォルトは "PycInvalidationMode.CHECKED_HASH" です。 それ以外の場合
   、デフォルトは "PycInvalidationMode.TIMESTAMP" です。

   バージョン 3.2 で変更: **PEP 3147** に準拠し *cfile* のデフォルト値
   を変更しました。以前のデフォルトは *file* + "'c'" (最適化が有効な場
   合は "'o'") でした。同時に *optimize* パラメータも追加されました。

   バージョン 3.4 で変更: バイトコードをキャッシュするファイルへの書き
   込みに "importlib" を使うようにコードを変更しました。これにより、例
   えば権限や write-and-move セマンティクスなどの、ファイルの作成や書
   き込みの動作が "importlib" と一致するようになりました。 *cfile* が
   シンボリックリンクであるか通常のファイルでない場合、
   "FileExistsError" を送出するという注意書きも追加されました。

   バージョン 3.7 で変更: **PEP 552** に従って *invalidation_mode* 引
   数が追加されました。 環境変数 "SOURCE_DATE_EPOCH" が設定されている
   場合、*invalidation_mode* は "PycInvalidationMode.CHECKED_HASH" に
   強制されます。

   バージョン 3.7.2 で変更: 環境変数 "SOURCE_DATE_EPOCH" は、
   *invalidation_mode* 引数の値を上書きせず、デフォルト値を決めるよう
   になりました。

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

class py_compile.PycInvalidationMode

   バイトコードファイルがソースファイルに対して最新かどうかをインター
   プリタが判定する方法を表す列挙型です。 ".pyc" ファイルのヘッダーに
   は、使用する無効化モードが記録されています。 Python が実行時に
   ".pyc" ファイルを無効化する方法について詳しくは、キャッシュされたバ
   イトコードの無効化 を参照してください。

   Added in version 3.7.

   TIMESTAMP

      ".pyc" ファイルにはソースファイルのタイムスタンプとサイズが含ま
      れます。 Python は実行時にこれらをソースファイルのメタデータと比
      較し、".pyc" ファイルを再生成する必要があるかを判定します。

   CHECKED_HASH

      ".pyc" ファイルにはソースファイルの内容のハッシュ値が含まれます
      。 Python は実行時にこれをソースと比較し、".pyc" ファイルを再生
      成する必要があるかを判定します。

   UNCHECKED_HASH

      "CHECKED_HASH" と同様に、".pyc" ファイルにはソースファイルの内容
      のハッシュ値が含まれます。 ただし Python は実行時に ".pyc" ファ
      イルが最新であるとみなし、ソースファイルとの照合を一切行いません
      。

      このオプションは、ビルドシステムなど Python の外部の仕組みで
      ".pyc" ファイルを最新に保つ場合に役立ちます。


コマンドラインインターフェイス
==============================

このモジュールはスクリプトとして実行し、複数のソースファイルをコンパイ
ルできます。 *filenames* で指定したファイルをコンパイルし、生成したバ
イトコードを通常の方法でキャッシュします。 このプログラムはディレクト
リ構造を検索してソースファイルを探すことはなく、明示的に指定したファイ
ルだけをコンパイルします。 いずれかのファイルをコンパイルできなかった
場合、終了ステータスはゼロ以外になります。

<file> ... <fileN>
-

   位置引数にはコンパイルするファイルを指定します。 引数が "-" だけの
   場合、ファイルのリストを標準入力から読み込みます。

-q, --quiet

   エラー出力を抑制します。

バージョン 3.2 で変更: "-" のサポートが追加されました。

バージョン 3.10 で変更: "-q" のサポートが追加されました。

参考:

  "compileall" モジュール
     ディレクトリツリー内の Python ソースファイルを全てコンパイルする
     ライブラリ。
