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 で指定したファイルをコンパイルし、生成したバイトコードを通常の方法でキャッシュします。 このプログラムはディレクトリ構造を検索してソースファイルを探すことはなく、明示的に指定したファイルだけをコンパイルします。 いずれかのファイルをコンパイルできなかった場合、終了ステータスはゼロ以外になります。
- -q, --quiet¶
エラー出力を抑制します。
バージョン 3.2 で変更: - のサポートが追加されました。
バージョン 3.10 で変更: -q のサポートが追加されました。
参考
compileallモジュールディレクトリツリー内の Python ソースファイルを全てコンパイルするライブラリ。