規則
py_binary
查看規則來源open_in_new
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)相關註解。Python 沒有 `py_embed_data`，但有 `cc_embed_data` 和 `go_embed_data`。這是因為 Python 有執行階段資源的概念。 |
imports
|
字串清單；預設值為 []
要新增至 PYTHONPATH 的匯入目錄清單。
須遵守「建立變數」替代規則。系統會為這項規則和所有依附於這項規則的規則新增這些匯入目錄 (注意：不是這項規則依附的規則)。依據這項規則的 `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` 中。如果未指定，系統會改用 `name`，並附加 `.py`。如果 `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
預先編譯檔案的最佳化層級。
如要進一步瞭解最佳化層級，請參閱 https://docs.python.org/3/library/functions.html#compile 的 `compile()` 函式 `optimize` 引數說明文件。
注意：值 `-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
查看規則來源open_in_new
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
來源檔案不再直接新增至 runfiles。
:::
引數
| 屬性 |
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)相關註解。Python 沒有 `py_embed_data`，但有 `cc_embed_data` 和 `go_embed_data`。這是因為 Python 有執行階段資源的概念。 |
imports
|
字串清單；預設值為 []
要新增至 PYTHONPATH 的匯入目錄清單。
須遵守「建立變數」替代規則。系統會為這項規則和所有依附於這項規則的規則新增這些匯入目錄 (注意：不是這項規則依附的規則)。依據這項規則的 `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
預先編譯檔案的最佳化層級。
如要進一步瞭解最佳化層級，請參閱 https://docs.python.org/3/library/functions.html#compile 的 `compile()` 函式 `optimize` 引數說明文件。
注意：值 `-1` 代表「目前的解譯器」，也就是「產生 pyc 時的建構時間」所用的解譯器，而非程式碼實際執行時的執行階段解譯器。
|
precompile_source_retention
|
字串；預設值為 "inherit"
編譯來源檔案時，決定是否將來源檔案保留在產生的輸出內容中。有效值如下：
* `inherit`：從 {flag}`--precompile_source_retention` 標記繼承值。
* `keep_source`：包含原始 Python 來源。* `omit_source`：不要加入原始的 py 來源。
|
srcs_version
|
字串；預設值為 "PY2AND3"
已停用，未使用，不會執行任何動作。
|
py_test
查看規則來源open_in_new
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)相關註解。Python 沒有 `py_embed_data`，但有 `cc_embed_data` 和 `go_embed_data`。這是因為 Python 有執行階段資源的概念。 |
imports
|
字串清單；預設值為 []
要新增至 PYTHONPATH 的匯入目錄清單。
須遵守「建立變數」替代規則。系統會為這項規則和所有依附於這項規則的規則新增這些匯入目錄 (注意：不是這項規則依附的規則)。依據這項規則的 `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` 中。如果未指定，系統會改用 `name`，並附加 `.py`。如果 `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
預先編譯檔案的最佳化層級。
如要進一步瞭解最佳化層級，請參閱 https://docs.python.org/3/library/functions.html#compile 的 `compile()` 函式 `optimize` 引數說明文件。
注意：值 `-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
查看規則來源open_in_new
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 涵蓋範圍工具的進入點。啟用涵蓋範圍時，目標及其 runfile 會新增至 runfile。
工具的進入點必須可由 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`) 和純檔案 Runfile (`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"
附加至啟動 Python 虛設常式指令碼的「Shebang」運算式，用於執行 {rule}`py_binary` 目標。如要瞭解動機，請參閱 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}
The {obj}`PyRuntimeInfo.zip_main_template` field.
:::
|
