Python 規則

回報問題 查看原始碼 Nightly · 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`：從 {flag}`--precompile` 標記判斷值。* `enabled`：在建構期間編譯 Python 來源檔案。請注意，--precompile_add_to_runfiles 會影響編譯檔案納入下游二進位檔的方式。* `disabled`：請勿在建構期間編譯 Python 來源檔案。* `if_generated_source`：編譯 Python 來源檔案，但僅限於這些檔案是產生的檔案。:::{seealso} * {flag}`--precompile` 標記，可在某些情況下覆寫此屬性，並在建構時影響所有目標。* {obj}`pyc_collection` 屬性，可針對個別目標依序啟用預先編譯。* [Precompiling](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 來源。* `omit_if_generated_source`：如果是一般來源檔案，則保留原始來源；如果是產生的檔案，則略過。
pyc_collection	字串；預設為 "inherit" 判斷是否應手動納入依附元件的 pyc 檔案。注意：此設定僅適用於 {flag}`--precompile_add_to_runfiles=decided_elsewhere`。 有效值如下： * `inherit`：繼承 {flag}`--pyc_collection` 中的值。 * `include_pyc`：在二進位檔中新增依附元件的 pyc 檔案 (來自 {obj}`PyInfo.transitive_pyc_files`)。 * `disabled`：不要明確新增依附元件的 pyc 檔案。請注意，如果目標將 pyc 檔案納入其執行檔案 (例如使用 {obj}`--precompile_add_to_runfiles=always` 時)，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 來源 * 來源的預先編譯構件。 注意：預先編譯會影響最終執行檔案中包含哪些預設輸出內容。詳情請參閱預先編譯相關的屬性和標記。

引數

屬性
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`：從 {flag}`--precompile` 標記判斷值。* `enabled`：在建構期間編譯 Python 來源檔案。請注意，--precompile_add_to_runfiles 會影響編譯檔案納入下游二進位檔的方式。* `disabled`：請勿在建構期間編譯 Python 來源檔案。* `if_generated_source`：編譯 Python 來源檔案，但僅限於這些檔案是產生的檔案。:::{seealso} * {flag}`--precompile` 標記，可在某些情況下覆寫此屬性，並在建構時影響所有目標。* {obj}`pyc_collection` 屬性，可針對個別目標依序啟用預先編譯。* [Precompiling](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 來源。* `omit_if_generated_source`：如果是一般來源檔案，則保留原始來源；如果是產生的檔案，則略過。
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`：從 {flag}`--precompile` 標記判斷值。* `enabled`：在建構期間編譯 Python 來源檔案。請注意，--precompile_add_to_runfiles 會影響編譯檔案納入下游二進位檔的方式。* `disabled`：請勿在建構期間編譯 Python 來源檔案。* `if_generated_source`：編譯 Python 來源檔案，但僅限於這些檔案是產生的檔案。:::{seealso} * {flag}`--precompile` 標記，可在某些情況下覆寫此屬性，並在建構時影響所有目標。* {obj}`pyc_collection` 屬性，可針對個別目標依序啟用預先編譯。* [Precompiling](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 來源。* `omit_if_generated_source`：如果是一般來源檔案，則保留原始來源；如果是產生的檔案，則略過。
pyc_collection	字串；預設為 "inherit" 判斷是否應手動納入依附元件的 pyc 檔案。注意：此設定僅適用於 {flag}`--precompile_add_to_runfiles=decided_elsewhere`。 有效值如下： * `inherit`：繼承 {flag}`--pyc_collection` 中的值。 * `include_pyc`：在二進位檔中新增依附元件的 pyc 檔案 (來自 {obj}`PyInfo.transitive_pyc_files`)。 * `disabled`：不要明確新增依附元件的 pyc 檔案。請注意，如果目標將 pyc 檔案納入其執行檔案 (例如使用 {obj}`--precompile_add_to_runfiles=always` 時)，pyc 檔案仍可能來自依附元件。
python_version	字串；預設為 "PY3" 已停用、未使用，不會執行任何動作。
srcs_version	字串；預設為 "PY2AND3" 已停用、未使用，不會執行任何動作。
stamp	整數；預設值為 0 是否將建構資訊編碼至二進位檔。可能的值： * `stamp = 1`：一律將建構資訊戳記至二進位檔，即使在 `--nostamp` 建構作業中也是如此。**請避免使用這項設定**，因為這可能會導致二進位檔的遠端快取功能和任何依賴該快取的後續動作失效。* `stamp = 0`：一律使用常數值取代版本資訊。這可提供良好的建構結果快取功能。* `stamp = -1`: 建構資訊的嵌入方式由 `--[no]stamp` 標記控制。除非依附元件變更，否則系統不會重建經過標記的二進位檔。警告：沖壓會降低快取命中率，進而影響建構效能，因此請盡量避免使用。

py_runtime

查看規則來源

py_runtime(name, 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	名稱 (必填) 這個目標的專屬名稱。
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	字串；預設為 "" 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` 欄位。:::