py_compile --- 編譯 Python 源文件?

源代碼: Lib/py_compile.py

py_compile 模塊提供了用來從源文件生成字節(jié)碼的函數(shù)和另一個用于當模塊源文件作為腳本被調(diào)用時的函數(shù)。

雖然不太常用，但這個函數(shù)在安裝共享模塊時還是很有用的，特別是當一些用戶可能沒有權(quán)限在包含源代碼的目錄中寫字節(jié)碼緩存文件時。

exception py_compile.PyCompileError?

當編譯文件過程中發(fā)生錯誤時，拋出的異常。

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

將源文件編譯成字節(jié)碼并寫出字節(jié)碼緩存文件。 源代碼從名為 file 的文件中加載。 字節(jié)碼會寫入到 cfile，默認為 PEP 3147/PEP 488 路徑，以 .pyc 結(jié)尾。 例如，如果 file 是 /foo/bar/baz.py 則對于 Python 3.2 cfile 將默認為 /foo/bar/__pycache__/baz.cpython-32.pyc。 如果指定了 dfile，則在錯誤信息中它將代替 file 作為源文件的名稱。 如果 doraise 為真值，則當編譯 file 遇到錯誤時將會引發(fā) PyCompileError。 如果 doraise 為假值（默認），則將錯誤信息寫入到 sys.stderr，但不會引發(fā)異常。 此函數(shù)返回編譯后字節(jié)碼文件的路徑，即 cfile 所使用的值。

doraise 和 quiet 參數(shù)確定在編譯文件時如何處理錯誤。 如果 quiet 為 0 或 1，并且 doraise 為假值，則會啟用默認行為：寫入錯誤信息到 sys.stderr，并且函數(shù)將返回 None 而非一個路徑。 如果 doraise 為真值，則將改為引發(fā) PyCompileError。 但是如果 quiet 為 2，則不會寫入消息，并且 doraise 也不會有效果。

如果 cfile 所表示（顯式指定或計算得出）的路徑為符號鏈接或非常規(guī)文件，則將引發(fā) FileExistsError。 此行為是用來警告如果允許寫入編譯后字節(jié)碼文件到這些路徑則導入操作將會把它們轉(zhuǎn)為常規(guī)文件。 這是使用文件重命名來將最終編譯后字節(jié)碼文件放置到位以防止并發(fā)文件寫入問題的導入操作的附帶效果。

optimize 控制優(yōu)化級別并會被傳給內(nèi)置的 compile() 函數(shù)。 默認值 -1 表示選擇當前解釋器的優(yōu)化級別。

invalidation_mode 應當是 PycInvalidationMode 枚舉的成員，它控制在運行時如何讓已生成的字節(jié)碼緩存失效。 如果設(shè)置了 SOURCE_DATE_EPOCH 環(huán)境變量則默認值為 PycInvalidationMode.CHECKED_HASH，否則默認值為 PycInvalidationMode.TIMESTAMP。

在 3.2 版更改: 將 cfile 的默認值改成與 PEP 3147 兼容。 之前的默認值是 file + 'c' (如果啟用優(yōu)化則為 'o')。 同時也添加了 optimize 形參。

在 3.4 版更改: 將代碼更改為使用 importlib 執(zhí)行字節(jié)碼緩存文件寫入。 這意味著文件創(chuàng)建/寫入的語義現(xiàn)在與 importlib 所做的相匹配，例如權(quán)限、寫入和移動語義等等。 同時也添加了當 cfile 為符號鏈接或非常規(guī)文件時引發(fā) FileExistsError 的預警設(shè)置。

在 3.7 版更改: invalidation_mode 形參是根據(jù) PEP 552 的描述添加的。 如果設(shè)置了 SOURCE_DATE_EPOCH 環(huán)境變量，invalidation_mode 將被強制設(shè)為 PycInvalidationMode.CHECKED_HASH。

在 3.7.2 版更改: SOURCE_DATE_EPOCH 環(huán)境變量不會再覆蓋 invalidation_mode 參數(shù)的值，而改為確定其默認值。

在 3.8 版更改: 增加了 quiet 形參。

class py_compile.PycInvalidationMode?

一個由可用方法組成的枚舉，解釋器可以用來確定字節(jié)碼文件是否與源文件保持一致。 .pyc 文件在其標頭中指明了所需的失效模式。 請參閱 已緩存字節(jié)碼的失效 了解有關(guān) Python 在運行時如何讓 .pyc 文件失效的更多信息。

3.7 新版功能.

TIMESTAMP?

.pyc 文件包括時間戳和源文件的大小，Python 將在運行時將其與源文件的元數(shù)據(jù)進行比較以確定 .pyc 文件是否需要重新生成。

CHECKED_HASH?

.pyc 文件包括源文件內(nèi)容的哈希值，Python 將在運行時將其與源文件內(nèi)容進行比較以確定 .pyc 文件是否需要重新生成。

UNCHECKED_HASH?

類似于 CHECKED_HASH，.pyc 文件包括源文件內(nèi)容的哈希值。 但是，Python 將在運行時假定 .pyc 文件是最新的而完全不會將 .pyc 與源文件進行驗證。

此選項適用于 .pycs 由 Python 以外的某個系統(tǒng)例如構(gòu)建系統(tǒng)來確保最新的情況。