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)

ソースファイルをバイトコードにコンパイルして、バイトコードのキャッシュファイルに書き出します。ソースコードはファイル名 file で渡します。バイトコードは cfile に書き込まれ、デフォルトでは PEP 3147PEP 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 です。

invalidation_mode should be a member of the PycInvalidationMode enum and controls how the generated bytecode cache is invalidated at runtime. The default is PycInvalidationMode.CHECKED_HASH if the SOURCE_DATE_EPOCH environment variable is set, otherwise the default is PycInvalidationMode.TIMESTAMP.

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

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

バージョン 3.7 で変更: The invalidation_mode parameter was added as specified in PEP 552. If the SOURCE_DATE_EPOCH environment variable is set, invalidation_mode will be forced to PycInvalidationMode.CHECKED_HASH.

バージョン 3.7.2 で変更: The SOURCE_DATE_EPOCH environment variable no longer overrides the value of the invalidation_mode argument, and determines its default value instead.

class py_compile.PycInvalidationMode

A enumeration of possible methods the interpreter can use to determine whether a bytecode file is up to date with a source file. The .pyc file indicates the desired invalidation mode in its header. See Cached bytecode invalidation for more information on how Python invalidates .pyc files at runtime.

バージョン 3.7 で追加.

TIMESTAMP

The .pyc file includes the timestamp and size of the source file, which Python will compare against the metadata of the source file at runtime to determine if the .pyc file needs to be regenerated.

CHECKED_HASH

The .pyc file includes a hash of the source file content, which Python will compare against the source at runtime to determine if the .pyc file needs to be regenerated.

UNCHECKED_HASH

Like CHECKED_HASH, the .pyc file includes a hash of the source file content. However, Python will at runtime assume the .pyc file is up to date and not validate the .pyc against the source file at all.

This option is useful when the .pycs are kept up to date by some system external to Python like a build system.

py_compile.main(args=None)

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

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

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

参考

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