Python 規則

規則

• 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, 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 = [":testlib"],
)

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 原始碼或共用資料庫的目錄，以及這些目錄的所有父項目錄 (不含存放區根目錄)。預設值 (auto) 表示除非使用 --incompatible_default_to_explicit_init_py。如果設為 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，產生的虛設常式指令碼仍可能在執行階段叫用錯誤的解譯器版本。請參閱這個解決方法，其會視需要定義指向任一 Python 版本的 py_runtime 目標，並透過設定 --python_top 來啟用這個 py_runtime。
srcs_version	String; optional; default is "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	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_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	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 原始碼或共用資料庫的目錄，以及這些目錄的所有父項目錄 (不含存放區根目錄)。預設值 (auto) 表示除非使用 --incompatible_default_to_explicit_init_py。如果設為 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，產生的虛設常式指令碼仍可能在執行階段叫用錯誤的解譯器版本。請參閱這個解決方法，其會視需要定義指向任一 Python 版本的 py_runtime 目標，並透過設定 --python_top 來啟用這個 py_runtime。
srcs_version	String; optional; default is "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	Integer; optional; default is 0 請參閱 py_binary() 引數一節，不過測試時戳記引數預設為 0。

py_runtime

py_runtime(name, 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 指令碼，能夠執行 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 此目標的專屬名稱。
coverage_tool	Label; optional 此目標用於從 py_binary 和 py_test 目標收集程式碼涵蓋率資訊。 如有設定，目標就必須產生單一檔案，或是必須是可執行的目標。單一檔案的路徑；如果目標為執行檔，則執行檔將決定 Python 涵蓋範圍工具的進入點。啟用涵蓋率後，目標及其執行檔案就會新增至執行檔案。 工具的進入點必須由 Python 解譯器 (例如 .py 或 .pyc 檔案) 載入。它必須接受 coverage.py 的指令列引數，且至少要有 run 和 lcov 子指令。
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 目標時所用 Bootstrastra Python 虛設常式指令碼。 請參閱問題 8685，瞭解使用動機。 不適用於 Windows。