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結尾。例如，如果 file 是/foo/bar/baz.py，則對於 Python 3.2，cfile 將預設為/foo/bar/__pycache__/baz.cpython-32.pyc。如果指定了 dfile，則將其用作原始檔的名稱，而不是 file，用於在異常回溯中顯示源行。如果 doraise 為 true，則在編譯 file 時遇到錯誤時會引發PyCompileError。如果 doraise 為 false（預設值），則會將錯誤字串寫入sys.stderr，但不會引發異常。此函式返回位元組碼編譯檔案的路徑，即所使用的 cfile 值。doraise 和 quiet 引數決定了編譯檔案時如何處理錯誤。如果 quiet 為 0 或 1，且 doraise 為 false，則啟用預設行為：錯誤字串將寫入
sys.stderr，函式返回None而不是路徑。如果 doraise 為 true，則會引發PyCompileError。但是，如果 quiet 為 2，則不寫入任何訊息，並且 doraise 無效。如果 cfile 最終的路徑（無論是顯式指定還是計算得出）是符號連結或非正則檔案，則會引發
FileExistsError。這是為了警告，如果允許將位元組碼編譯檔案寫入這些路徑，則匯入將把這些路徑轉換為正則檔案。這是匯入使用檔案重新命名將最終位元組碼編譯檔案放置到位以防止併發檔案寫入問題的副作用。optimize 控制最佳化級別並傳遞給內建的
compile()函式。預設值-1選擇當前直譯器的最佳化級別。invalidation_mode 應該是
PycInvalidationMode列舉的成員，並控制執行時如何使生成的位元組碼快取失效。如果設定了SOURCE_DATE_EPOCH環境變數，則預設值為PycInvalidationMode.CHECKED_HASH>，否則預設值為PycInvalidationMode.TIMESTAMP。版本 3.2 中更改: 將 cfile 的預設值更改為符合 PEP 3147。之前的預設值是 file +
'c'（如果啟用了最佳化，則為'o'）。同時添加了 optimize 引數。版本 3.4 中更改: 更改了程式碼，使用
importlib進行位元組碼快取檔案寫入。這意味著檔案建立/寫入語義現在與importlib的行為一致，例如許可權、寫入和移動語義等。同時添加了警告，如果 cfile 是符號連結或非正則檔案，則會引發FileExistsError。版本 3.7 中更改: 添加了 invalidation_mode 引數，如 PEP 552 中所述。如果設定了
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檔案失效的更多資訊，請參閱 快取位元組碼失效。在 3.7 版本加入。
- TIMESTAMP¶
.pyc檔案包含原始檔的時間戳和大小，Python 將在執行時與原始檔的元資料進行比較，以確定.pyc檔案是否需要重新生成。
- CHECKED_HASH¶
.pyc檔案包含原始檔內容的雜湊值，Python 將在執行時與原始檔進行比較，以確定.pyc檔案是否需要重新生成。
- UNCHECKED_HASH¶
與
CHECKED_HASH類似，.pyc檔案包含原始檔內容的雜湊值。然而，Python 在執行時將假定.pyc檔案是最新的，並且完全不驗證.pyc與原始檔的一致性。當
.pyc檔案由 Python 外部的某個系統（如構建系統）保持最新時，此選項很有用。
命令列介面¶
此模組可以作為指令碼呼叫以編譯多個原始檔。在 filenames 中命名的檔案將被編譯，並且生成的位元組碼將以通常的方式快取。此程式不搜尋目錄結構以查詢原始檔；它只編譯顯式命名的檔案。如果其中一個檔案無法編譯，則退出狀態碼為非零。
- -q, --quiet¶
抑制錯誤輸出。
版本 3.2 中更改: 添加了對 - 的支援。
版本 3.10 中更改: 添加了對 -q 的支援。
參見
- 模組
compileall 用於編譯目錄樹中所有 Python 原始檔的實用程式。