compileall — 位元組碼編譯 Python 庫

原始碼: Lib/compileall.py

此模組提供了一些實用函式來支援安裝 Python 庫。這些函式會編譯目錄樹中的 Python 原始檔。此模組可用於在庫安裝時建立快取的位元組碼檔案，這使得即使對庫目錄沒有寫入許可權的使用者也能使用這些檔案。

可用性：非 WASI。

此模組在 WebAssembly 上不起作用或不可用。有關更多資訊，請參閱 WebAssembly 平臺。

命令列使用

此模組可以作為指令碼（使用 python -m compileall）來編譯 Python 原始檔。

directory ...
file ...

位置引數是要編譯的檔案或包含原始檔的目錄，將遞迴遍歷。如果沒有給出引數，則行為類似於命令列是 -l <directories from sys.path>。

-l

不遞迴進入子目錄，只編譯命名或隱含目錄中直接包含的原始檔。

-f

即使時間戳是最新的，也強制重新構建。

-q

不列印已編譯檔案的列表。如果傳遞一次，錯誤訊息仍將列印。如果傳遞兩次（-qq），則所有輸出都將被抑制。

-d destdir

要編譯的每個檔案路徑字首的目錄。這會出現在編譯時回溯中，並也編譯到位元組碼檔案中，在原始檔在位元組碼檔案執行時不存在的情況下，它將用於回溯和其他訊息。

-s strip_prefix

從 .pyc 檔案中記錄的路徑中移除給定的字首。路徑相對於該字首。

此選項可與 -p 配合使用，但不能與 -d 配合使用。

-p prepend_prefix

將給定的字首新增到 .pyc 檔案中記錄的路徑。使用 -p / 使路徑變為絕對路徑。

此選項可與 -s 配合使用，但不能與 -d 配合使用。

-x regex

正則表示式用於搜尋每個考慮編譯的檔案的完整路徑，如果正則表示式產生匹配，則跳過該檔案。

-i list

讀取檔案 list，並將其包含的每一行新增到要編譯的檔案和目錄列表中。如果 list 是 -，則從 stdin 讀取行。

-b

將位元組碼檔案寫入其傳統位置和名稱，這可能會覆蓋由其他 Python 版本建立的位元組碼檔案。預設是將檔案寫入其 PEP 3147 位置和名稱，這允許多個 Python 版本的位元組碼檔案共存。

-r

控制子目錄的最大遞迴級別。如果給定此引數，則 -l 選項將不被考慮。python -m compileall <directory> -r 0 等同於 python -m compileall <directory> -l。

-j N

使用 N 個工作程序編譯給定目錄中的檔案。如果使用 0，則將使用 os.process_cpu_count() 的結果。

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

控制生成位元組碼檔案在執行時如何失效。timestamp 值表示將生成嵌入原始檔時間戳和大小的 .pyc 檔案。checked-hash 和 unchecked-hash 值會導致生成基於雜湊的 pyc 檔案。基於雜湊的 pyc 檔案嵌入原始檔內容的雜湊值而不是時間戳。有關 Python 在執行時如何驗證位元組碼快取檔案的更多資訊，請參閱 快取位元組碼失效。如果未設定 SOURCE_DATE_EPOCH 環境變數，則預設值為 timestamp；如果已設定 SOURCE_DATE_EPOCH 環境變數，則預設值為 checked-hash。

-o level

使用給定的最佳化級別進行編譯。可以多次使用以同時編譯多個級別（例如，compileall -o 1 -o 2）。

-e dir

忽略指向給定目錄之外的符號連結。

如果兩個具有不同最佳化級別的 .pyc 檔案具有相同的內容，則使用硬連結合併重複檔案。

3.2 版中已更改: 添加了 -i, -b 和 -h 選項。

3.5 版中已更改: 添加了 -j, -r 和 -qq 選項。-q 選項被更改為多級值。-b 將始終生成以 .pyc 結尾的位元組碼檔案，永不生成 .pyo。

3.7 版中已更改: 添加了 --invalidation-mode 選項。

3.9 版中已更改: 添加了 -s, -p, -e 和 --hardlink-dupes 選項。將預設遞迴限制從 10 提高到 sys.getrecursionlimit()。添加了多次指定 -o 選項的可能性。

沒有命令列選項來控制 compile() 函式使用的最佳化級別，因為 Python 直譯器本身已經提供了該選項: python -O -m compileall。

同樣，compile() 函式遵循 sys.pycache_prefix 設定。生成的位元組碼快取只有在 compile() 執行時使用與執行時相同的 sys.pycache_prefix（如果有）時才有用。

公共函式

compileall.compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

遞迴遍歷由 dir 命名的目錄樹，並編譯所有 .py 檔案。如果所有檔案都成功編譯，則返回真值，否則返回假值。

maxlevels 引數用於限制遞迴的深度；它預設為 sys.getrecursionlimit()。

如果給定 ddir，它將被新增到每個被編譯的檔案路徑之前，用於編譯時回溯，並且也會被編譯到位元組碼檔案中，在原始檔在位元組碼檔案執行時不存在的情況下，它將用於回溯和其他訊息。

如果 force 為真，即使時間戳是最新的，模組也會被重新編譯。

如果給定 rx，其 search 方法將對每個考慮編譯的檔案的完整路徑呼叫，如果返回真值，則跳過該檔案。這可用於排除與正則表示式匹配的檔案，該正則表示式以 re.Pattern 物件給出。

如果 quiet 為 False 或 0（預設），則檔名和其他資訊將列印到標準輸出。設定為 1，只打印錯誤。設定為 2，則所有輸出都將被抑制。

如果 legacy 為真，則位元組碼檔案將寫入其傳統位置和名稱，這可能會覆蓋由其他 Python 版本建立的位元組碼檔案。預設是將檔案寫入其 PEP 3147 位置和名稱，這允許多個 Python 版本的位元組碼檔案共存。

optimize 指定編譯器的最佳化級別。它被傳遞給內建的 compile() 函式。也接受最佳化級別序列，這導致在一次呼叫中對一個 .py 檔案進行多次編譯。

引數 workers 指定用於並行編譯檔案的 worker 數量。預設是不使用多個 worker。如果平臺不能使用多個 worker 且給定 workers 引數，則將使用順序編譯作為備用方案。如果 workers 為 0，則使用系統中的核心數量。如果 workers 小於 0，則會引發 ValueError。

invalidation_mode 應該是 py_compile.PycInvalidationMode 列舉的成員，並控制生成的 pyc 在執行時如何失效。

stripdir、prependdir 和 limit_sl_dest 引數對應於上面描述的 -s、-p 和 -e 選項。它們可以指定為 str 或 os.PathLike。

如果 hardlink_dupes 為真，並且兩個具有不同最佳化級別的 .pyc 檔案具有相同的內容，則使用硬連結合併重複檔案。

3.2 版中已更改: 添加了 legacy 和 optimize 引數。

3.5 版中已更改: 添加了 workers 引數。

3.5 版中已更改: quiet 引數更改為多級值。

3.5 版中已更改: 無論 optimize 的值是什麼，legacy 引數都只寫入 .pyc 檔案，而不寫入 .pyo 檔案。

在 3.6 版本發生變更: 接受 path-like object。

3.7 版中已更改: 添加了 invalidation_mode 引數。

3.7.2 版中已更改: invalidation_mode 引數的預設值更新為 None。

3.8 版中已更改: 現在將 workers 設定為 0 會選擇最佳核心數。

3.9 版中已更改: 添加了 stripdir, prependdir, limit_sl_dest 和 hardlink_dupes 引數。maxlevels 的預設值從 10 更改為 sys.getrecursionlimit()

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

編譯路徑為 fullname 的檔案。如果檔案編譯成功，則返回真值，否則返回假值。

如果給定 ddir，它將被新增到被編譯檔案路徑之前，用於編譯時回溯，並且也會被編譯到位元組碼檔案中，在原始檔在位元組碼檔案執行時不存在的情況下，它將用於回溯和其他訊息。

如果給定 rx，其 search 方法將傳遞給被編譯檔案的完整路徑名，如果返回真值，則不編譯該檔案並返回 True。這可用於排除與正則表示式匹配的檔案，該正則表示式以 re.Pattern 物件給出。

如果 quiet 為 False 或 0（預設），則檔名和其他資訊將列印到標準輸出。設定為 1，只打印錯誤。設定為 2，則所有輸出都將被抑制。

如果 legacy 為真，則位元組碼檔案將寫入其傳統位置和名稱，這可能會覆蓋由其他 Python 版本建立的位元組碼檔案。預設是將檔案寫入其 PEP 3147 位置和名稱，這允許多個 Python 版本的位元組碼檔案共存。

optimize 指定編譯器的最佳化級別。它被傳遞給內建的 compile() 函式。也接受最佳化級別序列，這導致在一次呼叫中對一個 .py 檔案進行多次編譯。

invalidation_mode 應該是 py_compile.PycInvalidationMode 列舉的成員，並控制生成的 pyc 在執行時如何失效。

stripdir、prependdir 和 limit_sl_dest 引數對應於上面描述的 -s、-p 和 -e 選項。它們可以指定為 str 或 os.PathLike。

如果 hardlink_dupes 為真，並且兩個具有不同最佳化級別的 .pyc 檔案具有相同的內容，則使用硬連結合併重複檔案。

在 3.2 版本加入。

3.5 版中已更改: quiet 引數更改為多級值。

3.5 版中已更改: 無論 optimize 的值是什麼，legacy 引數都只寫入 .pyc 檔案，而不寫入 .pyo 檔案。

3.7 版中已更改: 添加了 invalidation_mode 引數。

3.7.2 版中已更改: invalidation_mode 引數的預設值更新為 None。

3.9 版中已更改: 添加了 stripdir, prependdir, limit_sl_dest 和 hardlink_dupes 引數。

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

位元組碼編譯在 sys.path 中找到的所有 .py 檔案。如果所有檔案都成功編譯，則返回真值，否則返回假值。

如果 skip_curdir 為真（預設值），則當前目錄不包含在搜尋中。所有其他引數都傳遞給 compile_dir() 函式。請注意，與其他編譯函式不同，maxlevels 預設為 0。

3.2 版中已更改: 添加了 legacy 和 optimize 引數。

3.5 版中已更改: quiet 引數更改為多級值。

3.5 版中已更改: 無論 optimize 的值是什麼，legacy 引數都只寫入 .pyc 檔案，而不寫入 .pyo 檔案。

3.7 版中已更改: 添加了 invalidation_mode 引數。

3.7.2 版中已更改: invalidation_mode 引數的預設值更新為 None。

要強制重新編譯 Lib/ 子目錄及其所有子目錄中的所有 .py 檔案

import compileall

compileall.compile_dir('Lib/', force=True)

# Perform same compilation, excluding files in .svn directories.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

# pathlib.Path objects can also be used.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)

參見

模組 py_compile

位元組碼編譯單個原始檔。