Python 規則

回報問題 查看原始碼

規則

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 (例如執行 Python 二進位檔以在 java_test 內設定部分模擬資源),正確的方法就是讓其他二進位檔或測試依附於其資料區段中的 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

Name; required

此目標的專屬名稱。


如果未指定 main,其應與應用程式主要進入點的來源檔案名稱相同,減去副檔名。舉例來說,如果進入點稱為 main.py,則名稱應為 main
deps

List of labels; optional

要連結至二進位檔目標的其他程式庫清單。請查看deps 多數建構規則定義的一般屬性的一般評論。 通常是 py_library 規則。
srcs

List of labels; required

系統為了建立目標而處理的來源 (.py) 檔案清單。 包括所有已檢查的程式碼和任何產生的來源檔案。因此,程式庫目標會位於 deps,而執行階段所需的其他二進位檔案則屬於 data
imports

List of strings; optional

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

且必須遵循「Make 變數」替代條件。系統會為這項規則及所有依附於這項規則的規則新增匯入目錄 (注意:並非這項規則的適用規則)。每個目錄都會依此規則適用的 py_binary 規則新增至 PYTHONPATH

禁止使用絕對路徑 (以 / 開頭的路徑) 和參照執行根目錄上方的路徑,會導致錯誤。

legacy_create_init

Integer; optional; default is -1

是否要在執行檔案樹狀結構中隱含建立空白的 __init__.py 檔案。 系統會在每個包含 Python 原始碼或共用程式庫的目錄中,以及這些目錄的所有父項目錄 (不包括存放區根目錄) 建立目錄。除非使用 --incompatible_default_to_explicit_init_py,否則預設值預設為自動表示 true。如果設為 false,使用者應負責建立 (也許是空的) __init__.py 檔案,並視需要將這些檔案新增至 Python 目標的 srcs
main

Label; optional

應用程式主要進入點的來源檔案名稱。 此檔案也必須列在 srcs 中。如未指定,系統會改用 name (如上所示)。如果 name 不符合 srcs 中的任何檔案名稱,則必須指定 main
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

為 Python 2 或 Python 3 建構這個目標 (及其轉換 deps)。有效值為 "PY2""PY3" (預設值)。

無論指令列上指定的版本或其他相依於此版本的目標更高,Python 版本一律會重設 (可能預設) 到這個屬性指定的版本。

如果您想要在目前的 Python 版本上 select(),可以檢查 @rules_python//python:python_version 的值。詳情請參閱這裡的說明。

錯誤警告:這個屬性會設定 Bazel 用來建構目標版本,但由於 #4815,產生的虛設常式指令碼可能會在執行階段叫用錯誤的解譯版本。請參閱這個解決方法,瞭解如何定義 py_runtime 目標,視需要指向任一 Python 版本,然後設定 --python_top 來啟用這個 py_runtime

srcs_version

String; optional; default is "PY2AND3"

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

允許的值為 "PY2AND3""PY2""PY3""PY2ONLY""PY3ONLY" 值也是基於歷史因素而允許,但基本上與 "PY2""PY3" 相同,因此應避免使用。

請注意,只有執行檔規則 (py_binarypy_library ) 實際會根據這個屬性的值驗證目前的 Python 版本。(這是功能;由於 py_library 不會變更目前的 Python 版本,因此如果在驗證的情況下,您將無法在同一個叫用中建構 PY2ONLYPY3ONLY 程式庫)。此外,如果發生版本不相符的情況,則系統只會在執行階段中回報錯誤。請特別注意,這項錯誤不會出現在 bazel build --nobuild 叫用中。)

如要取得診斷版本中版本需求的相關診斷資訊,您可以在目標上執行 find_requirements 層面:

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
          
這會建立具有後置字串 -pyversioninfo.txt 的檔案,說明目標為何需要一個 Python 版本或其他版本。請注意,即使指定的目標因版本衝突而無法建構,系統也能正常運作。

stamp

Integer; optional; default is -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

Name; required

此目標的專屬名稱。

deps

List of labels; optional

要連結至二進位檔目標的其他程式庫清單。請查看deps 多數建構規則定義的一般屬性的一般評論。 通常是 py_library 規則。
srcs

List of labels; optional

系統為了建立目標而處理的來源 (.py) 檔案清單。 包括所有已檢查的程式碼和任何產生的來源檔案。
imports

List of strings; optional

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

且必須遵循「Make 變數」替代條件。系統會為這項規則及所有依附於這項規則的規則新增匯入目錄 (注意:並非這項規則的適用規則)。每個目錄都會依此規則適用的 py_binary 規則新增至 PYTHONPATH

禁止使用絕對路徑 (以 / 開頭的路徑) 和參照執行根目錄上方的路徑,會導致錯誤。

srcs_version

String; optional; default is "PY2AND3"

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

允許的值為 "PY2AND3""PY2""PY3""PY2ONLY""PY3ONLY" 值也是基於歷史因素而允許,但基本上與 "PY2""PY3" 相同,因此應避免使用。

請注意,只有執行檔規則 (py_binarypy_library ) 實際會根據這個屬性的值驗證目前的 Python 版本。(這是功能;由於 py_library 不會變更目前的 Python 版本,因此如果在驗證的情況下,您將無法在同一個叫用中建構 PY2ONLYPY3ONLY 程式庫)。此外,如果發生版本不相符的情況,則系統只會在執行階段中回報錯誤。請特別注意,這項錯誤不會出現在 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

Name; required

此目標的專屬名稱。

deps

List of labels; optional

要連結至二進位檔目標的其他程式庫清單。請查看deps 多數建構規則定義的一般屬性的一般評論。 通常是 py_library 規則。
srcs

List of labels; required

系統為了建立目標而處理的來源 (.py) 檔案清單。 包括所有已檢查的程式碼和任何產生的來源檔案。因此,程式庫目標會位於 deps,而執行階段所需的其他二進位檔案則屬於 data
imports

List of strings; optional

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

且必須遵循「Make 變數」替代條件。系統會為這項規則及所有依附於這項規則的規則新增匯入目錄 (注意:並非這項規則的適用規則)。每個目錄都會依此規則適用的 py_binary 規則新增至 PYTHONPATH

禁止使用絕對路徑 (以 / 開頭的路徑) 和參照執行根目錄上方的路徑,會導致錯誤。

legacy_create_init

Integer; optional; default is -1

是否要在執行檔案樹狀結構中隱含建立空白的 __init__.py 檔案。 系統會在每個包含 Python 原始碼或共用程式庫的目錄中,以及這些目錄的所有父項目錄 (不包括存放區根目錄) 建立目錄。除非使用 --incompatible_default_to_explicit_init_py,否則預設值預設為自動表示 true。如果設為 false,使用者應負責建立 (也許是空的) __init__.py 檔案,並視需要將這些檔案新增至 Python 目標的 srcs
main

Label; optional

應用程式主要進入點的來源檔案名稱。 此檔案也必須列在 srcs 中。如未指定,系統會改用 name (如上所示)。如果 name 不符合 srcs 中的任何檔案名稱,則必須指定 main
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

為 Python 2 或 Python 3 建構這個目標 (及其轉換 deps)。有效值為 "PY2""PY3" (預設值)。

無論指令列上指定的版本或其他相依於此版本的目標更高,Python 版本一律會重設 (可能預設) 到這個屬性指定的版本。

如果您想要在目前的 Python 版本上 select(),可以檢查 @rules_python//python:python_version 的值。詳情請參閱這裡的說明。

錯誤警告:這個屬性會設定 Bazel 用來建構目標版本,但由於 #4815,產生的虛設常式指令碼可能會在執行階段叫用錯誤的解譯版本。請參閱這個解決方法,瞭解如何定義 py_runtime 目標,視需要指向任一 Python 版本,然後設定 --python_top 來啟用這個 py_runtime

srcs_version

String; optional; default is "PY2AND3"

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

允許的值為 "PY2AND3""PY2""PY3""PY2ONLY""PY3ONLY" 值也是基於歷史因素而允許,但基本上與 "PY2""PY3" 相同,因此應避免使用。

請注意,只有執行檔規則 (py_binarypy_library ) 實際會根據這個屬性的值驗證目前的 Python 版本。(這是功能;由於 py_library 不會變更目前的 Python 版本,因此如果在驗證的情況下,您將無法在同一個叫用中建構 PY2ONLYPY3ONLY 程式庫)。此外,如果發生版本不相符的情況,則系統只會在執行階段中回報錯誤。請特別注意,這項錯誤不會出現在 bazel build --nobuild 叫用中。)

如要取得診斷版本中版本需求的相關診斷資訊,您可以在目標上執行 find_requirements 層面:

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
          
這會建立具有後置字串 -pyversioninfo.txt 的檔案,說明目標為何需要一個 Python 版本或其他版本。請注意,即使指定的目標因版本衝突而無法建構,系統也能正常運作。

stamp

Integer; optional; default is 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

Name; required

此目標的專屬名稱。

bootstrap_template

Label; optional; default is @bazel_tools//tools/python:python_bootstrap_template.txt

先前稱為「Python stub 指令碼」,這是每個 Python 執行檔目標的進入點。
coverage_tool

Label; optional

這是用於從 py_binarypy_test 目標收集程式碼涵蓋範圍資訊的目標。

設定目標之後,目標必須產生一個檔案,或者必須是可執行的目標。單一檔案的路徑,或目標為執行檔時,執行檔會決定 Python 涵蓋率工具的進入點。涵蓋率啟用之後,目標及其執行檔案將會新增至執行檔。

該工具的進入點必須由 Python 解譯器 (例如 .py.pyc 檔案) 載入。其必須接受 coverage.py 的指令列引數,並至少包含 runlcov 子指令。

files

List of labels; optional

對內建執行階段而言,這是指構成這個執行階段的一組檔案。這些檔案將會新增至使用這個執行階段的 Python 二進位檔的執行檔案。如果是平台執行階段,則不應設定這個屬性。
interpreter

Label; optional

針對內建執行階段,這是叫用解譯器的目標。如果是平台執行階段,則不應設定這個屬性。
interpreter_path

String; optional

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

String; optional; default is "_INTERNAL_SENTINEL"

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

預設值是由 --incompatible_py3_is_default 旗標控制。不過,這個屬性日後將成為必要屬性,且沒有預設值。

stub_shebang

String; optional; default is "#!/usr/bin/env python3"

「Shebang」運算式前面加上執行 py_binary 目標時的開機 Python 指令碼。

如需激勵,請參閱問題 8685

不適用於 Windows。