Python 規則

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

規則

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 目錄樹狀結構，其中包含程式在執行階段所需的所有程式碼和資料，以及一個 Stub 指令碼，可透過正確的初始環境和資料啟動程式。

範例

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

名稱 (必填)

這個目標的專屬名稱。


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

標籤清單；預設為 []

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

標籤清單 (必要)

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

字串清單；預設為 []

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

適用於 "Make 變數" 替換。這些匯入目錄會新增至此規則和所有依附此規則的規則 (請注意：並非此規則依附的規則)。每個目錄都會透過依賴此規則的 py_binary 規則新增至 PYTHONPATH。

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

整數，預設值為 -1

是否要在 runfiles 樹狀結構中隱含建立空白的 __init__.py 檔案。這些檔案會在每個含有 Python 原始碼或共用程式庫的目錄，以及這些目錄的每個父目錄中建立，但不含存放區根目錄。預設值為 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 版本一律會重設為此屬性指定的版本 (可能為預設值)。

如果您想在目前的 Python 版本上執行 select()，可以檢查 @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 的匯入目錄清單。

適用於 "Make 變數" 替換。這些匯入目錄會新增至此規則和所有依附此規則的規則 (請注意：並非此規則依附的規則)。每個目錄都會透過依賴此規則的 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 的匯入目錄清單。

適用於 "Make 變數" 替換。系統會將這些匯入目錄新增至這項規則及依附於該規則的所有規則 (注意：這項規則並非依附的規則，每個目錄都會透過依賴此規則的 py_binary 規則新增至 PYTHONPATH。

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

整數，預設值為 -1

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

標籤；預設為 None

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

字串；不可設定；預設值為 "_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

字串；預設為 "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"

執行 py_binary 目標時，在用於啟動程序 Python 指令碼的前面加上「Shebang」運算式。

請參閱問題 8685瞭解動機。

不適用於 Windows。