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，則 cfile 將預設為 Python 3.2 的/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 版本中更改: 根據 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檔案失效的更多資訊，請參見 快取位元組碼失效。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 原始檔的實用工具。