Python 規則

回報問題查看原始碼 Nightly · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

規則

py_binary
py_library
py_test
py_runtime

py_binary

py_binary(name, deps, srcs, data, args, compatible_with, deprecation, distribs, env, exec_compatible_with, exec_properties, features, imports, legacy_create_init, licenses, main, output_licenses, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, python_version, restricted_to, srcs_version, stamp, tags, target_compatible_with, testonly, toolchains, visibility)

引數

屬性
`name`	名稱；必填這個目標的專屬名稱。
`deps`	標籤清單；預設為 `[]` 要連結至目標的其他程式庫清單。請參閱有關 [`deps` 屬性](https://bazel.build/reference/be/common-definitions#typical-attributes)的註解，這類屬性通常由規則定義。這些通常是 `py_library` 規則。僅提供在執行階段使用的資料檔案的目標，屬於 `data` 屬性。
`srcs`	標籤清單 (必要) 系統在建立目標時所處理的 Python 來源檔案清單。這包括所有已簽入的程式碼，也可能包括產生的來源檔案。`.py` 檔案屬於 `srcs`，而程式庫目標屬於 `deps`。在執行階段可能需要的其他二進位檔案則屬於 `data`。
`data`	標籤清單；預設為 `[]` 這個程式庫在執行階段所需的檔案清單。請參閱有關 [`data` 屬性](https://bazel.build/reference/be/common-definitions#typical-attributes)的註解，這類屬性通常由規則定義。沒有 `py_embed_data`，但有 `cc_embed_data` 和 `go_embed_data`，這是因為 Python 有執行階段資源的概念。
`imports`	字串清單；預設為 `[]` 要新增至 PYTHONPATH 的匯入目錄清單。適用於「Make 變數」替換。這些匯入目錄會為此規則和所有依附此規則的規則新增 (注意：不是此規則依附的規則)。每個目錄都會透過依賴此規則的 `py_binary` 規則新增至 `PYTHONPATH`。字串為 repo-runfiles-root 相對路徑，不允許使用絕對路徑 (開頭為 `/`) 和參照執行根目錄上方路徑的路徑，否則會導致錯誤。
`legacy_create_init`	整數；預設值為 `-1` 是否要在 runfiles 樹狀結構中隱含建立空白的 `__init__.py` 檔案。這些檔案會在包含 Python 原始碼或共用程式庫的每個目錄，以及這些目錄的每個父項目錄中建立，但不包含存放區根目錄。預設值 `-1` (自動) 表示為 true，除非使用 `--incompatible_default_to_explicit_init_py`。如果為 false，使用者必須負責建立 (可能為空白) `__init__.py` 檔案，並視需要將這些檔案新增至 Python 目標的 `srcs`。
`main`	標籤；預設為 `None` 選用；應用程式主要進入點的來源檔案名稱。這個檔案也必須列在 `srcs` 中。如果未指定，系統會改用附加了 `.py` 的 `name`。如果 `name` 與 `srcs` 中的任何檔案名稱不相符，則必須指定 `main`。
`precompile`	字串；預設為 `"inherit"` 是否應針對這個目標的 py 來源檔案進行預先編譯。值： * `inherit`：允許下游二進位檔決定是否使用預先編譯的檔案。* `enabled`：在建構期間編譯 Python 來源檔案。* `disabled`：請勿在建構期間編譯 Python 來源檔案。:::{seealso} * {flag}`--precompile` 標記，可在某些情況下覆寫此屬性，並在建構時影響所有目標。* {obj}`pyc_collection` 屬性，可針對個別目標依序啟用預先編譯。* [預先編譯](precompiling) 說明文件，提供有關使用預先編譯功能的指南。:::
`precompile_invalidation_mode`	字串；預設為 `"auto"` 如何驗證預先編譯的檔案是否與相關的來源檔案保持一致。可能的值如下： * `auto`：有效值會由其他建構設定自動決定。* `checked_hash`：如果來源檔案的雜湊與 pyc 檔案中記錄的雜湊相符，就會使用 pyc 檔案。在處理可能需要修改的程式碼時，這項功能最實用。* `unchecked_hash`：一律使用 pyc 檔案；不要將 pyc 的雜湊值與來源檔案進行比對。這項功能最適合用於不會修改程式碼的情況。如要進一步瞭解 pyc 無效模式，請參閱 https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode。
`precompile_optimize_level`	整數；預設值為 `0` 預先編譯檔案的最佳化等級。如要進一步瞭解最佳化層級，請參閱 `compile()` 函式的 `optimize` 引數說明文件，網址為 https://docs.python.org/3/library/functions.html#compile 注意：值 `-1` 表示「目前的解譯器」，也就是在產生 pyc 的建構期間使用的解譯器，而不是在程式碼實際執行時的執行階段使用的解譯器。
`precompile_source_retention`	字串；預設為 `"inherit"` 在編譯來源檔案時，決定是否保留來源檔案的結果輸出內容。有效值如下： * `inherit`：從 {flag}`--precompile_source_retention` 標記繼承值。* `keep_source`：包含原始 Python 來源。* `omit_source`：不納入原始 py 來源。
`pyc_collection`	字串；預設為 `"inherit"` 判斷是否應手動納入依附元件的 pyc 檔案。有效值如下： * `inherit`：繼承 {flag}`--precompile` 的值。 * `include_pyc`：從依附元件新增隱含產生的 pyc 檔案。也就是說，如果指定了 {attr}`precompile="inherit"`，則會為目標新增 pyc 檔案。 * `disabled`：不新增隱含產生的 pyc 檔案。請注意，pyc 檔案仍可能來自於可在目標層級啟用預先編譯的依附元件。
`python_version`	字串；預設為 `"PY3"` 已停用、未使用，不會執行任何動作。
`srcs_version`	字串；預設為 `"PY2AND3"` 已停用、未使用，不會執行任何動作。
`stamp`	整數；預設值為 `-1` 是否將建構資訊編碼至二進位檔。可能的值： * `stamp = 1`：一律將建構資訊戳記到二進位檔案中，即使在 `--nostamp` 建構作業中也是如此。請避免使用這項設定，因為這可能會導致二進位檔的遠端快取功能和任何依賴該功能的後續動作失效。* `stamp = 0`：一律以常數值取代版本資訊。這可提供良好的建構結果快取功能。* `stamp = -1`: 建構資訊的嵌入方式由 `--[no]stamp` 標記控制。除非依附元件變更，否則系統不會重建經過標記的二進位檔。警告：沖壓會降低快取命中率，進而影響建構效能，因此請盡量避免使用。

py_library

查看規則來源

py_library(name, deps, srcs, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, imports, licenses, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, restricted_to, srcs_version, tags, target_compatible_with, testonly, toolchains, visibility)

可依附的 Python 程式碼程式庫。預設輸出項目： * 輸入的 Python 來源 * 來源的預先編譯構件。注意：預先編譯會影響產生的執行檔案中包含哪些預設輸出內容。詳情請參閱預先編譯相關的屬性和標記。:::{versionchanged} 0.37.0 來源檔案不再直接新增至執行檔。:::

引數

屬性
`name`	名稱；必填這個目標的專屬名稱。
`deps`	標籤清單；預設為 `[]` 要連結至目標的其他程式庫清單。請參閱有關 [`deps` 屬性](https://bazel.build/reference/be/common-definitions#typical-attributes)的註解，這類屬性通常由規則定義。這些通常是 `py_library` 規則。僅提供在執行階段使用的資料檔案的目標，屬於 `data` 屬性。
`srcs`	標籤清單；預設為 `[]` 系統在建立目標時所處理的 Python 來源檔案清單。這包括所有已簽入的程式碼，也可能包括產生的來源檔案。`.py` 檔案屬於 `srcs`，而程式庫目標屬於 `deps`。在執行階段可能需要的其他二進位檔案則屬於 `data`。
`data`	標籤清單；預設為 `[]` 這個程式庫在執行階段所需的檔案清單。請參閱有關 [`data` 屬性](https://bazel.build/reference/be/common-definitions#typical-attributes)的註解，這類屬性通常由規則定義。沒有 `py_embed_data`，但有 `cc_embed_data` 和 `go_embed_data`，這是因為 Python 有執行階段資源的概念。
`imports`	字串清單；預設為 `[]` 要新增至 PYTHONPATH 的匯入目錄清單。適用於「Make 變數」替換。這些匯入目錄會為此規則和所有依附此規則的規則新增 (注意：不是此規則依附的規則)。每個目錄都會透過依賴此規則的 `py_binary` 規則新增至 `PYTHONPATH`。字串為 repo-runfiles-root 相對路徑，不允許使用絕對路徑 (開頭為 `/`) 和參照執行根目錄上方路徑的路徑，否則會導致錯誤。
`precompile`	字串；預設為 `"inherit"` 是否應針對這個目標的 py 來源檔案進行預先編譯。值： * `inherit`：允許下游二進位檔決定是否使用預先編譯的檔案。* `enabled`：在建構期間編譯 Python 來源檔案。* `disabled`：請勿在建構期間編譯 Python 來源檔案。:::{seealso} * {flag}`--precompile` 標記，可在某些情況下覆寫此屬性，並在建構時影響所有目標。* {obj}`pyc_collection` 屬性，可針對個別目標依序啟用預先編譯。* [預先編譯](precompiling) 說明文件，提供有關使用預先編譯功能的指南。:::
`precompile_invalidation_mode`	字串；預設為 `"auto"` 如何驗證預先編譯的檔案是否與相關的來源檔案保持一致。可能的值如下： * `auto`：有效值會由其他建構設定自動決定。* `checked_hash`：如果來源檔案的雜湊與 pyc 檔案中記錄的雜湊相符，就會使用 pyc 檔案。在處理可能需要修改的程式碼時，這項功能最實用。* `unchecked_hash`：一律使用 pyc 檔案；不要將 pyc 的雜湊值與來源檔案進行比對。這項功能最適合用於不會修改程式碼的情況。如要進一步瞭解 pyc 無效模式，請參閱 https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode。
`precompile_optimize_level`	整數；預設值為 `0` 預先編譯檔案的最佳化等級。如要進一步瞭解最佳化層級，請參閱 `compile()` 函式的 `optimize` 引數說明文件，網址為 https://docs.python.org/3/library/functions.html#compile 注意：值 `-1` 表示「目前的解譯器」，也就是在產生 pyc 的建構期間使用的解譯器，而不是在程式碼實際執行時的執行階段使用的解譯器。
`precompile_source_retention`	字串；預設為 `"inherit"` 在編譯來源檔案時，決定是否保留來源檔案的結果輸出內容。有效值如下： * `inherit`：從 {flag}`--precompile_source_retention` 標記繼承值。* `keep_source`：包含原始 Python 來源。* `omit_source`：不納入原始 py 來源。
`srcs_version`	字串；預設為 `"PY2AND3"` 已停用、未使用，不會執行任何動作。

py_test

查看規則來源

py_test(name, deps, srcs, data, args, compatible_with, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, imports, legacy_create_init, licenses, local, main, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility)

引數

屬性
`name`	名稱；必填這個目標的專屬名稱。
`deps`	標籤清單；預設為 `[]` 要連結至目標的其他程式庫清單。請參閱有關 [`deps` 屬性](https://bazel.build/reference/be/common-definitions#typical-attributes)的註解，這類屬性通常由規則定義。這些通常是 `py_library` 規則。僅提供在執行階段使用的資料檔案的目標，屬於 `data` 屬性。
`srcs`	標籤清單 (必要) 系統在建立目標時所處理的 Python 來源檔案清單。這包括所有已簽入的程式碼，也可能包括產生的來源檔案。`.py` 檔案屬於 `srcs`，而程式庫目標屬於 `deps`。在執行階段可能需要的其他二進位檔案則屬於 `data`。
`data`	標籤清單；預設為 `[]` 這個程式庫在執行階段所需的檔案清單。請參閱有關 [`data` 屬性](https://bazel.build/reference/be/common-definitions#typical-attributes)的註解，這類屬性通常由規則定義。沒有 `py_embed_data`，但有 `cc_embed_data` 和 `go_embed_data`，這是因為 Python 有執行階段資源的概念。
`imports`	字串清單；預設為 `[]` 要新增至 PYTHONPATH 的匯入目錄清單。適用於「Make 變數」替換。這些匯入目錄會為此規則和所有依附此規則的規則新增 (注意：不是此規則依附的規則)。每個目錄都會透過依賴此規則的 `py_binary` 規則新增至 `PYTHONPATH`。字串為 repo-runfiles-root 相對路徑，不允許使用絕對路徑 (開頭為 `/`) 和參照執行根目錄上方路徑的路徑，否則會導致錯誤。
`legacy_create_init`	整數；預設值為 `-1` 是否要在 runfiles 樹狀結構中隱含建立空白的 `__init__.py` 檔案。這些檔案會在包含 Python 原始碼或共用程式庫的每個目錄，以及這些目錄的每個父項目錄中建立，但不包含存放區根目錄。預設值 `-1` (自動) 表示為 true，除非使用 `--incompatible_default_to_explicit_init_py`。如果為 false，使用者必須負責建立 (可能為空白) `__init__.py` 檔案，並視需要將這些檔案新增至 Python 目標的 `srcs`。
`main`	標籤；預設為 `None` 選用；應用程式主要進入點的來源檔案名稱。這個檔案也必須列在 `srcs` 中。如果未指定，系統會改用附加了 `.py` 的 `name`。如果 `name` 與 `srcs` 中的任何檔案名稱不相符，則必須指定 `main`。
`precompile`	字串；預設為 `"inherit"` 是否應針對這個目標的 py 來源檔案進行預先編譯。值： * `inherit`：允許下游二進位檔決定是否使用預先編譯的檔案。* `enabled`：在建構期間編譯 Python 來源檔案。* `disabled`：請勿在建構期間編譯 Python 來源檔案。:::{seealso} * {flag}`--precompile` 標記，可在某些情況下覆寫此屬性，並在建構時影響所有目標。* {obj}`pyc_collection` 屬性，可針對個別目標依序啟用預先編譯。* [預先編譯](precompiling) 說明文件，提供有關使用預先編譯功能的指南。:::
`precompile_invalidation_mode`	字串；預設為 `"auto"` 如何驗證預先編譯的檔案是否與相關的來源檔案保持一致。可能的值如下： * `auto`：有效值會由其他建構設定自動決定。* `checked_hash`：如果來源檔案的雜湊與 pyc 檔案中記錄的雜湊相符，就會使用 pyc 檔案。在處理可能需要修改的程式碼時，這項功能最實用。* `unchecked_hash`：一律使用 pyc 檔案；不要將 pyc 的雜湊值與來源檔案進行比對。這項功能最適合用於不會修改程式碼的情況。如要進一步瞭解 pyc 無效模式，請參閱 https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode。
`precompile_optimize_level`	整數；預設值為 `0` 預先編譯檔案的最佳化等級。如要進一步瞭解最佳化層級，請參閱 `compile()` 函式的 `optimize` 引數說明文件，網址為 https://docs.python.org/3/library/functions.html#compile 注意：值 `-1` 表示「目前的解譯器」，也就是在產生 pyc 的建構期間使用的解譯器，而不是在程式碼實際執行時的執行階段使用的解譯器。
`precompile_source_retention`	字串；預設為 `"inherit"` 在編譯來源檔案時，決定是否保留來源檔案的結果輸出內容。有效值如下： * `inherit`：從 {flag}`--precompile_source_retention` 標記繼承值。* `keep_source`：包含原始 Python 來源。* `omit_source`：不納入原始 py 來源。
`pyc_collection`	字串；預設為 `"inherit"` 判斷是否應手動納入依附元件的 pyc 檔案。有效值如下： * `inherit`：繼承 {flag}`--precompile` 的值。 * `include_pyc`：從依附元件新增隱含產生的 pyc 檔案。也就是說，如果指定了 {attr}`precompile="inherit"`，則會為目標新增 pyc 檔案。 * `disabled`：不新增隱含產生的 pyc 檔案。請注意，pyc 檔案仍可能來自於可在目標層級啟用預先編譯的依附元件。
`python_version`	字串；預設為 `"PY3"` 已停用、未使用，不會執行任何動作。
`srcs_version`	字串；預設為 `"PY2AND3"` 已停用、未使用，不會執行任何動作。
`stamp`	整數；預設值為 `0` 是否將建構資訊編碼至二進位檔。可能的值： * `stamp = 1`：一律將建構資訊戳記到二進位檔案中，即使在 `--nostamp` 建構作業中也是如此。請避免使用這項設定，因為這可能會導致二進位檔的遠端快取功能和任何依賴該功能的後續動作失效。* `stamp = 0`：一律以常數值取代版本資訊。這可提供良好的建構結果快取功能。* `stamp = -1`: 建構資訊的嵌入方式由 `--[no]stamp` 標記控制。除非依附元件變更，否則系統不會重建經過標記的二進位檔。警告：沖壓會降低快取命中率，進而影響建構效能，因此請盡量避免使用。

py_runtime

查看規則來源

py_runtime(name, abi_flags, bootstrap_template, compatible_with, coverage_tool, deprecation, distribs, exec_compatible_with, exec_properties, features, files, implementation_name, interpreter, interpreter_path, interpreter_version_info, pyc_tag, python_version, restricted_to, stage2_bootstrap_template, stub_shebang, tags, target_compatible_with, testonly, toolchains, visibility, zip_main_template)

代表用於執行 Python 程式碼的 Python 執行階段。`py_runtime` 目標可以代表「平台執行階段」或「內建執行階段」。平台執行階段會存取系統安裝的解譯器，而內建執行階段則會指向可執行的目標，以便做為解譯器。無論是哪種情況，「解譯器」都代表任何可執行的二進位檔或包裝函式指令碼，能夠執行在指令列上傳遞的 Python 指令碼，並遵循標準 CPython 解譯器的慣例。平台執行階段本質上並非密封的。它會對目標平台設下要求，要求該平台在特定路徑中提供解譯器。內建的執行階段可能或不具備密封性，這取決於它是否指向已簽入的轉譯器，或是指向存取系統轉譯器的包裝函式指令碼。範例 ``` load("@rules_python//python:py_runtime.bzl", "py_runtime") py_runtime( name = "python-2.7.12", files = glob(["python-2.7.12/**"]), interpreter = "python-2.7.12/bin/python", ) py_runtime( name = "python-3.6.0", interpreter_path = "/opt/pyenv/versions/3.6.0/bin/python", ) ```

引數

屬性
`name`	名稱；必填這個目標的專屬名稱。
`abi_flags`	字串；預設為 `""` 執行階段的 ABI 旗標，也就是 `sys.abiflags`。如果未設定，系統會根據旗標設定。
`bootstrap_template`	標籤；預設為 `"@rules_python//python/private:bootstrap_template"` 要使用的 Bootstrap 指令碼範本檔案。應包含 %python_binary%、%workspace_name%、%main% 和 %imports%。這個範本展開後，就會成為用於啟動程序的可執行檔案，因此會負責執行初始引導程序動作，例如尋找 Python 轉譯器、執行檔案，以及建構環境以執行指定的 Python 應用程式。雖然這個屬性目前為選用屬性，但當 Python 規則移出 Bazel 時，就會變成必要屬性。展開的確切變數名稱為不穩定的 API，可能會變更。將 Python 規則移出 Bazel 後，API 就會變得更穩定。如需更多變數，請參閱 @bazel_tools//tools/python:python_bootstrap_template.txt。
`coverage_tool`	標籤；預設為 `None` 這是用於從 {rule}`py_binary` 和 {rule}`py_test` 目標收集程式碼涵蓋率資訊的目標。如果已設定，目標必須產生單一檔案，或可執行的目標。單一檔案的路徑，或可執行檔 (如果目標是可執行檔)，會決定 Python 涵蓋率工具的進入點。啟用涵蓋率時，目標及其執行檔會新增至執行檔。工具的進入點必須可由 Python 解譯器載入 (例如 `.py` 或 `.pyc` 檔案)。它必須接受 [`coverage.py`](https://coverage.readthedocs.io) 的命令列引數，至少包含 `run` 和 `lcov` 子命令。
`files`	標籤清單；預設為 `[]` 對於建構內執行階段，這是組成這個執行階段的檔案組合。這些檔案會新增至使用此執行階段的 Python 二進位檔的執行檔。對於平台執行階段，則不得設定這項屬性。
`implementation_name`	字串；預設為 `"cpython"` Python 實作名稱 (`sys.implementation.name`)
`interpreter`	標籤；預設為 `None` 對於建構中的執行階段，這是要以解譯器方式叫用的目標。可以是下列任一項目： * 單一檔案，即為解譯器二進位檔。假設這些轉譯器是自給自足的單一檔案可執行檔，或是在 `files` 中指定的任何支援檔案。 * 可執行的目標。目標的可執行檔會是轉譯器二進位檔。系統會自動納入任何其他預設輸出內容 (`target.files`) 和一般檔案執行檔 (`runfiles.files`)，就像在 `files` 屬性中指定的一樣。注意：目標的執行檔可能尚未正確地尊重/傳播至工具鍊/轉譯器的使用者，請參閱 bazelbuild/rules_python/issues/1612。對於平台執行階段 (即已設定 `interpreter_path`)，則不得設定此屬性。
`interpreter_path`	字串；預設為 `""` 對於平台執行階段，這是目標平台上 Python 解譯器的絕對路徑。對於內建執行階段，則不得設定這項屬性。
`interpreter_version_info`	字典：字串 -> 字串；預設為 `{}` 這個執行階段提供的轉譯器版本資訊。如果未指定，則會使用 {obj}`--python_version`。支援的鍵會與 `sys.version_info` 的名稱相符。雖然輸入值是字串，但大多會轉換為整數。支援的鍵如下： * major：int，主要版本號碼 * minor：int，次要版本號碼 * micro：可選 int，微版本號碼 * releaselevel：可選 str，版本等級 * serial：可選 int，版本的序號 :::{versionchanged} 0.36.0 {obj}`--python_version` 會決定預設值。:::
`pyc_tag`	字串；預設為 `""` 選用字串；pyc 檔案名稱的標記部分，例如 `foo.cpython-39.pyc` 的 `cpython-39` 中綴。請參閱 PEP 3147。如果未指定，系統會根據 `implementation_name` 和 `interpreter_version_info` 計算。如果沒有可用的 pyc_tag，則只有無來源的 pyc 產生作業才能正常運作。
`python_version`	字串；預設為 `"PY3"` 這個執行階段是否適用於 Python 主要版本 2 或 3。有效值為 `"PY2"` 和 `"PY3"`。預設值由 `--incompatible_py3_is_default` 標記控制。不過，日後這項屬性將為必填，且沒有預設值。
`stage2_bootstrap_template`	標籤；預設為 `"@rules_python//python/private:stage2_bootstrap_template"` 啟用兩階段引導程序時使用的範本 :::{seealso} {obj}`PyRuntimeInfo.stage2_bootstrap_template` 和 {obj}`--bootstrap_impl` :::
`stub_shebang`	字串；預設為 `"#!/usr/bin/env python3"` 在執行 {rule}`py_binary` 目標時，會在引導式 Python 存根腳本前方加上「Shebang」運算式。請參閱 https://github.com/bazelbuild/bazel/issues/8685 瞭解原因。不適用於 Windows。
`zip_main_template`	標籤；預設為 `"@rules_python//python/private:zip_main_template"` 用於 zip 頂層 `__main__.py` 檔案的範本。這會成為執行 `python foo.zip` 時執行的進入點。:::{seealso} {obj}`PyRuntimeInfo.zip_main_template` 欄位。:::