Python 规则

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

规则

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

名称；必需

此目标的唯一名称。


如果未指定 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 版本始终会重置（可能默认）为此属性指定的任何版本。

如果您想对当前 Python 版本执行 select()，可以检查 @rules_python//python:python_version 的值。如需了解详情，请参阅 此处 。

bug 警告： 此属性设置 Bazel 构建目标所用的版本， 但由于 #4815，生成的桩脚本在运行时可能仍会调用错误的解释器版本。请参阅 此 问题解决方案，其中涉及定义一个 py_runtime 目标，该目标根据需要指向任一 Python 版本，并通过设置此 py_runtime 来激活 --python_top。

srcs_version

字符串；默认值为 "PY2AND3"

此属性声明目标的 srcs 与 Python 2、Python 3 或两者都兼容。如需实际设置 Python 运行时版本，请使用 python_version属性的可执行 Python 规则（py_binary或py_test）。

允许的值包括："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 版本或另一个 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_version属性的可执行 Python 规则（py_binary或py_test）。

允许的值包括："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 版本或另一个 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 版本始终会重置（可能默认）为此属性指定的任何版本。

如果您想对当前 Python 版本执行 select()，可以检查 @rules_python//python:python_version 的值。如需了解详情，请参阅 此处 。

bug 警告： 此属性设置 Bazel 构建目标所用的版本， 但由于 #4815，生成的桩脚本在运行时可能仍会调用错误的解释器版本。请参阅 此 问题解决方案，其中涉及定义一个 py_runtime 目标，该目标根据需要指向任一 Python 版本，并通过设置此 py_runtime 来激活 --python_top。

srcs_version

字符串；默认值为 "PY2AND3"

此属性声明目标的 srcs 与 Python 2、Python 3 或两者都兼容。如需实际设置 Python 运行时版本，请使用 python_version属性的可执行 Python 规则（py_binary或py_test）。

允许的值包括："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 版本或另一个 Python 版本的信息。请注意，即使 给定目标因版本冲突而构建失败，此方法也有效。
stamp

整数；默认值为 0

请参阅有关 py_binary() 实参的部分，但测试的 stamp 实参默认设置为 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 覆盖率工具的入口点。启用覆盖率后，目标及其 runfiles 将添加到 runfiles 中。

该工具的入口点必须可由 Python 解释器（例如 a .py 或 .pyc 文件）加载。它必须接受命令行实参 的 coverage.py，至少包括 run 和 lcov 子命令。

files

标签列表；默认值为 []

对于构建内运行时，这是构成此运行时的一组文件。这些文件将 添加到使用此运行时的 Python 二进制文件的 runfiles 中。对于平台运行时 不得设置此属性。
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。