py_compile --- 編譯 Python 源文件?

源代碼: Lib/py_compile.py

py_compile 模塊提供了用來(lái)從源文件生成字節碼的函數和另一個(gè)用于當模塊源文件作為腳本被調用時(shí)的函數。

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

exception py_compile.PyCompileError?

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

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

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

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

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

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

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

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

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

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

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

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

class py_compile.PycInvalidationMode?

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

3.7 新版功能.

TIMESTAMP?

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

CHECKED_HASH?

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

UNCHECKED_HASH?

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

此選項適用于 .pycs 由 Python 以外的某個(gè)系統例如構建系統來(lái)確保最新的情況。