32.10. "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)

   ソースファイルをバイトコードにコンパイルして、バイトコードのキャッ
   シュファイルに書き出します。ソースコードはファイル名 *file* で渡し
   ます。バイトコードは *cfile* に書き込まれ、デフォルトでは **PEP
   3147** や **PEP 488** にある ".pyc" で終わるパスです。例えば、
   *file* が "/foo/bar/baz.py" だった場合、 *cfile* は Python 3.2 では
   デフォルトで "/foo/bar/__pycache__/baz.cpython-32.pyc" になります。
   もし *dfile* が指定されたら、 *file* の代わりにソースファイルの名前
   としてエラーメッセージの中で使われます。 *doraise* が真の場合、コン
   パイル中にエラーが発生すると "PyCompileError" を送出します。
   *doraise* が (デフォルトである) 偽の場合はエラーメッセージは
   "sys.stderr" に出力されますが、例外は送出しません。この関数はバイト
   コンパイルされたファイルへのパス、つまり実際に使われた *cfile* の値
   を返します。

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

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

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

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

py_compile.main(args=None)

   いくつか複数のソースファイルをコンパイルします。 *args* で (あるい
   は *args* が "None" であればコマンドラインで) 指定されたファイルを
   コンパイルし、できたバイトコードを通常の方法で保存します。この関数
   はソースファイルの存在するディレクトリを検索しません; 指定されたフ
   ァイルをコンパイルするだけです。 args が "'-'" 1つだけだった場合、
   ファイルのリストは標準入力から取られます。

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

このモジュールがスクリプトとして実行されると、 "main()" がコマンドライ
ンで指定されたファイルを全てコンパイルします。一つでもコンパイルできな
いファイルがあると終了ステータスが 0 でない値になります。

参考:

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