compileall — 位元組編譯 Python 庫

原始碼: Lib/compileall.py

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

可用性: not WASI.

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

命令列使用

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

directory ...
file ...

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

-l

不要遞迴到子目錄中，僅編譯直接包含在命名或隱含目錄中的原始碼檔案。

-f

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

-q

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

-d destdir

前置到正在編譯的每個檔案的路徑的目錄。 這將出現在編譯時的回溯中，並且還會編譯到位元組碼檔案中，如果原始碼在執行位元組碼檔案時不存在，它將用於回溯和其他訊息中。

-s strip_prefix
-p prepend_prefix

刪除（-s）或附加（-p）記錄在 .pyc 檔案中的路徑的給定字首。 不能與 -d 結合使用。

-x regex

regex 用於搜尋要編譯的每個檔案的完整路徑，如果 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 設定。只有在執行時使用相同的 sys.pycache_prefix （如果有）執行 compile() 時，生成的位元組碼快取才有用。

公共函式

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 檔案。如果所有檔案都成功編譯，則返回 True 值，否則返回 False 值。

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

如果給定 ddir，它會新增到正在編譯的每個檔案的路徑前面，以便在編譯時進行回溯，並且還會編譯到位元組碼檔案中，在位元組碼檔案執行時，如果原始檔不存在，它將在回溯和其他訊息中使用。

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

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

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

如果 legacy 為 True，則位元組碼檔案將寫入其舊位置和名稱，這可能會覆蓋由另一個 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 為 True 且兩個具有不同最佳化級別的 .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 的檔案。如果該檔案成功編譯，則返回 True 值，否則返回 False 值。

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

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

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

如果 legacy 為 true，位元組碼檔案將被寫入其舊的位置和名稱，這可能會覆蓋由其他 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 為 True 且兩個具有不同最佳化級別的 .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 為 true（預設值），則搜尋中不包括當前目錄。所有其他引數都傳遞給 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

位元組編譯單個原始檔。