Python 規則

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

規則

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, python_version, restricted_to, srcs_version, stamp, tags, target_compatible_with, testonly, toolchains, visibility)

py_binary 是可執行的 Python 程式，由一組 .py 來源檔案 (可能屬於其他 py_library 規則)、*.runfiles 目錄樹狀結構 (內含程式在執行階段所需的所有程式碼和資料)，以及啟動程式的虛設常式指令碼 (具有正確的初始環境和資料) 組成。

範例

py_binary(
    name = "foo",
    srcs = ["foo.py"],
    data = [":transform"],  # a cc_binary which we invoke at run time
    deps = [
        ":foolib",  # a py_library
    ],
)

如要從其他二進位檔或測試中執行 py_binary (例如，從 java_test 中執行 Python 二進位檔，設定一些模擬資源)，正確做法是讓其他二進位檔或測試依附於資料區段中的 py_binary。其他二進位檔隨後即可找到相對於來源目錄的 py_binary。

py_binary(
    name = "test_main",
    srcs = ["test_main.py"],
    deps = [":testing"],
)

java_library(
    name = "testing",
    srcs = glob(["*.java"]),
    data = [":test_main"]
)

引數

屬性
name

名稱：必填

這個目標的專屬名稱。


如果未指定 main，這應與應用程式主要進入點的來源檔案名稱相同，但須扣除副檔名。舉例來說，如果您的進入點名為 main.py，則名稱應為 main。
deps

標籤清單；預設值為 []

要連結至二進位目標的其他程式庫清單。 如要查看有關 deps 的一般註解，請參閱「 大多數建構規則定義的典型屬性」。這些通常是 py_library 規則。
srcs

標籤清單 (必要)

系統會處理來源 (.py) 檔案清單，以建立目標。 包括所有已簽入的程式碼和產生的來源檔案。程式庫目標應位於 deps 中，而執行階段需要的其他二進位檔則應位於 data 中。
imports

字串清單；預設值為 []

要新增至 PYTHONPATH 的匯入目錄清單。

須遵守「建立變數」替代規則。系統會為這項規則和所有依附於這項規則的規則新增這些匯入目錄 (注意：不是這項規則依附的規則)。每個目錄都會透過取決於這項規則的 py_binary 規則，新增至 PYTHONPATH。

絕對路徑 (以 / 開頭的路徑) 和參照執行根目錄上方路徑的路徑均不允許，否則會導致錯誤。
legacy_create_init

整數；預設值為 -1

是否要在 Runfiles 樹狀結構中隱含建立空白的 __init__.py 檔案。 這些檔案會建立在含有 Python 原始碼或共用程式庫的每個目錄，以及這些目錄的每個父項目錄中，存放區根目錄除外。預設值為 auto，表示 true，除非使用 --incompatible_default_to_explicit_init_py。如果為 false，使用者必須建立 (可能為空白) __init__.py 檔案，並視需要將這些檔案新增至 Python 目標的 srcs。
main

標籤；預設值為 None

應用程式主要進入點的來源檔案名稱。 這個檔案也必須列在 srcs 中。如未指定，則會改為使用 name (詳見上文)。如果 name 與 srcs 中的任何檔案名稱都不相符，則必須指定 main。
python_version

字串；不可設定；預設值為 "_INTERNAL_SENTINEL"

是否要為 Python 2 或 Python 3 建構這個目標 (及其遞移性 deps)。有效值為 "PY2" 和 "PY3" (預設值)。

無論是在命令列上指定，還是由依附於此的其他較高目標指定，Python 版本一律會重設 (可能預設) 為這個屬性指定的版本。

如要select()目前的 Python 版本，可以檢查 @rules_python//python:python_version 的值。詳情請參閱這篇文章。

錯誤警告：這個屬性會設定 Bazel 建構目標時使用的版本，但由於 #4815，產生的虛設常式指令碼在執行階段可能仍會叫用錯誤的解譯器版本。請參閱這個解決方法，其中包含定義 py_runtime 目標 (視需要指向任一 Python 版本)，並透過設定 --python_top 啟用這個 py_runtime。
srcs_version

字串；預設值為 "PY2AND3"

這項屬性會宣告目標的 srcs 與 Python 2、Python 3 或兩者皆相容。如要實際設定 Python 執行階段版本，請使用可執行 Python 規則 (py_binary 或 py_test) 的 python_version 屬性。

允許的值為："PY2AND3"、"PY2" 和 "PY3"。 基於歷史因素，系統也允許使用 "PY2ONLY" 和 "PY3ONLY" 值，但這些值與 "PY2" 和 "PY3" 本質上相同，因此應避免使用。

請注意，只有可執行的規則 (py_binary 和 py_library ) 會根據這個屬性的值，實際驗證目前的 Python 版本。 (這是項功能；由於 py_library 不會變更目前的 Python 版本，如果進行驗證，就無法在同一次呼叫中建構 PY2ONLY 和 PY3ONLY 程式庫)。此外，如果版本不符，系統只會在執行階段回報錯誤。特別是錯誤不會出現在 bazel build --nobuild 呼叫中。)

如要取得診斷資訊，瞭解哪些依附元件會導入版本需求，請在目標上執行 find_requirements 層面：

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
這會建構一個帶有 -pyversioninfo.txt 後置字元的檔案，提供目標需要特定 Python 版本的相關資訊。請注意，即使指定目標因版本衝突而建構失敗，這項功能仍可運作。
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, restricted_to, srcs_version, tags, target_compatible_with, testonly, visibility)

引數

屬性
name

名稱：必填

這個目標的專屬名稱。
deps

標籤清單；預設值為 []

要連結至二進位目標的其他程式庫清單。 如要查看有關 deps 的一般註解，請參閱「 大多數建構規則定義的典型屬性」。這些通常是 py_library 規則。
srcs

標籤清單；預設值為 []

系統會處理來源 (.py) 檔案清單，以建立目標。 包括所有已簽入的程式碼和產生的來源檔案。
imports

字串清單；預設值為 []

要新增至 PYTHONPATH 的匯入目錄清單。

須遵守「建立變數」替代規則。系統會為這項規則和所有依附於這項規則的規則新增這些匯入目錄 (注意：不是這項規則依附的規則)。每個目錄都會透過取決於這項規則的 py_binary 規則，新增至 PYTHONPATH。

絕對路徑 (以 / 開頭的路徑) 和參照執行根目錄上方路徑的路徑均不允許，否則會導致錯誤。
srcs_version

字串；預設值為 "PY2AND3"

這項屬性會宣告目標的 srcs 與 Python 2、Python 3 或兩者皆相容。如要實際設定 Python 執行階段版本，請使用可執行 Python 規則 (py_binary 或 py_test) 的 python_version 屬性。

允許的值為："PY2AND3"、"PY2" 和 "PY3"。 基於歷史因素，系統也允許使用 "PY2ONLY" 和 "PY3ONLY" 值，但這些值與 "PY2" 和 "PY3" 本質上相同，因此應避免使用。

請注意，只有可執行的規則 (py_binary 和 py_library ) 會根據這個屬性的值，實際驗證目前的 Python 版本。 (這是項功能；由於 py_library 不會變更目前的 Python 版本，如果進行驗證，就無法在同一次呼叫中建構 PY2ONLY 和 PY3ONLY 程式庫)。此外，如果版本不符，系統只會在執行階段回報錯誤。特別是錯誤不會出現在 bazel build --nobuild 呼叫中。)

如要取得診斷資訊，瞭解哪些依附元件會導入版本需求，請在目標上執行 find_requirements 層面：

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
這會建構一個帶有 -pyversioninfo.txt 後置字元的檔案，提供目標需要特定 Python 版本的相關資訊。請注意，即使指定目標因版本衝突而建構失敗，這項功能仍可運作。

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, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility)

py_test() 規則會編譯測試。測試是某些測試程式碼周圍的二進位封裝函式。

範例

py_test(
    name = "runtest_test",
    srcs = ["runtest_test.py"],
    deps = [
        "//path/to/a/py/library",
    ],
)

您也可以指定主要模組：

py_test(
    name = "runtest_test",
    srcs = [
        "runtest_main.py",
        "runtest_lib.py",
    ],
    main = "runtest_main.py",
)

引數

屬性
name

名稱：必填

這個目標的專屬名稱。
deps

標籤清單；預設值為 []

要連結至二進位目標的其他程式庫清單。 如要查看有關 deps 的一般註解，請參閱「 大多數建構規則定義的典型屬性」。這些通常是 py_library 規則。
srcs

標籤清單 (必要)

系統會處理來源 (.py) 檔案清單，以建立目標。 包括所有已簽入的程式碼和產生的來源檔案。程式庫目標應位於 deps 中，而執行階段需要的其他二進位檔則應位於 data 中。
imports

字串清單；預設值為 []

要新增至 PYTHONPATH 的匯入目錄清單。

須遵守「建立變數」替代規則。系統會為這項規則和所有依附於這項規則的規則新增這些匯入目錄 (注意：不是這項規則依附的規則)。每個目錄都會透過取決於這項規則的 py_binary 規則，新增至 PYTHONPATH。

絕對路徑 (以 / 開頭的路徑) 和參照執行根目錄上方路徑的路徑均不允許，否則會導致錯誤。
legacy_create_init

整數；預設值為 -1

是否要在 Runfiles 樹狀結構中隱含建立空白的 __init__.py 檔案。 這些檔案會建立在含有 Python 原始碼或共用程式庫的每個目錄，以及這些目錄的每個父項目錄中，存放區根目錄除外。預設值為 auto，表示 true，除非使用 --incompatible_default_to_explicit_init_py。如果為 false，使用者必須建立 (可能為空白) __init__.py 檔案，並視需要將這些檔案新增至 Python 目標的 srcs。
main

標籤；預設值為 None

應用程式主要進入點的來源檔案名稱。 這個檔案也必須列在 srcs 中。如未指定，則會改為使用 name (詳見上文)。如果 name 與 srcs 中的任何檔案名稱都不相符，則必須指定 main。
python_version

字串；不可設定；預設值為 "_INTERNAL_SENTINEL"

是否要為 Python 2 或 Python 3 建構這個目標 (及其遞移性 deps)。有效值為 "PY2" 和 "PY3" (預設值)。

無論是在命令列上指定，還是由依附於此的其他較高目標指定，Python 版本一律會重設 (可能預設) 為這個屬性指定的版本。

如要select()目前的 Python 版本，可以檢查 @rules_python//python:python_version 的值。詳情請參閱這篇文章。

錯誤警告：這個屬性會設定 Bazel 建構目標時使用的版本，但由於 #4815，產生的虛設常式指令碼在執行階段可能仍會叫用錯誤的解譯器版本。請參閱這個解決方法，其中包含定義 py_runtime 目標 (視需要指向任一 Python 版本)，並透過設定 --python_top 啟用這個 py_runtime。
srcs_version

字串；預設值為 "PY2AND3"

這項屬性會宣告目標的 srcs 與 Python 2、Python 3 或兩者皆相容。如要實際設定 Python 執行階段版本，請使用可執行 Python 規則 (py_binary 或 py_test) 的 python_version 屬性。

允許的值為："PY2AND3"、"PY2" 和 "PY3"。 基於歷史因素，系統也允許使用 "PY2ONLY" 和 "PY3ONLY" 值，但這些值與 "PY2" 和 "PY3" 本質上相同，因此應避免使用。

請注意，只有可執行的規則 (py_binary 和 py_library ) 會根據這個屬性的值，實際驗證目前的 Python 版本。 (這是項功能；由於 py_library 不會變更目前的 Python 版本，如果進行驗證，就無法在同一次呼叫中建構 PY2ONLY 和 PY3ONLY 程式庫)。此外，如果版本不符，系統只會在執行階段回報錯誤。特別是錯誤不會出現在 bazel build --nobuild 呼叫中。)

如要取得診斷資訊，瞭解哪些依附元件會導入版本需求，請在目標上執行 find_requirements 層面：

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
這會建構一個帶有 -pyversioninfo.txt 後置字元的檔案，提供目標需要特定 Python 版本的相關資訊。請注意，即使指定目標因版本衝突而建構失敗，這項功能仍可運作。
stamp

整數；預設值為 0

請參閱 py_binary() 引數一節，但測試的預設戳記引數會設為 0。

py_runtime

查看規則來源 
py_runtime(name, bootstrap_template, compatible_with, coverage_tool, deprecation, distribs, features, files, interpreter, interpreter_path, licenses, python_version, restricted_to, stub_shebang, tags, target_compatible_with, testonly, visibility)

代表用於執行 Python 程式碼的 Python 執行階段。

py_runtime 目標可代表平台執行階段或建構內執行階段。平台執行階段會存取已知路徑的系統安裝解譯器，而建構內執行階段則會指向做為解譯器的可執行目標。在這兩種情況下，「解譯器」是指任何可執行的二進位檔或包裝函式指令碼，能夠執行在指令列上傳遞的 Python 指令碼，並遵循與標準 CPython 解譯器相同的慣例。

平台執行階段本質上並非密封。這項功能會要求目標平台在特定路徑中設有解譯器。視其是否指向已簽入的解譯器，或存取系統解譯器的包裝函式指令碼而定，建構內建的執行階段可能或可能不是密封的。

範例：

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

標籤；預設值為 "@bazel_tools//tools/python:python_bootstrap_template.txt"

先前稱為「Python 存根指令碼」，這是每個 Python 可執行目標的進入點。
coverage_tool

標籤；預設值為 None

這是用來從 py_binary 和 py_test 目標收集程式碼涵蓋範圍資訊的目標。

如果已設定，目標必須產生單一檔案，或是可執行的目標。 單一檔案的路徑，或目標為可執行檔時的可執行檔路徑，會決定 Python 涵蓋範圍工具的進入點。啟用涵蓋範圍時，目標及其執行檔會新增至執行檔。

工具的進入點必須可由 Python 解譯器載入 (例如 .py 或 .pyc 檔案)。它必須接受 coverage.py 的命令列引數，至少包括 run 和 lcov 子指令。
files

標籤清單；預設值為 []

如果是建構內執行階段，這就是組成該執行階段的一組檔案。這些檔案會新增至使用這個執行階段的 Python 二進位檔的執行檔案。如果是平台執行階段，則不得設定這項屬性。
interpreter

標籤；預設值為 None

如果是建構內建的執行階段，這是要叫用為解譯器的目標。如果是平台執行階段，則不得設定這項屬性。
interpreter_path

字串；預設值為 ""

如果是平台執行階段，這是目標平台上的 Python 解譯器絕對路徑。如果是內建執行階段，則不得設定這項屬性。
python_version

字串；預設值為 "_INTERNAL_SENTINEL"

這個執行階段適用於 Python 主要版本 2 或 3。有效值為 "PY2" 和 "PY3"。

預設值由 --incompatible_py3_is_default 旗標控管。 不過，這個屬性日後將成為必填屬性，且沒有預設值。

stub_shebang

字串；預設值為 "#!/usr/bin/env python3"

附加至啟動 Python 指令碼的「Shebang」運算式，用於執行 py_binary 目標。

請參閱問題 8685，瞭解動機。

不適用於 Windows。