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 的导入目录列表。

“使变量”为替代项。系统会为此规则以及与其关联的所有规则添加这些导入目录(注意:不会添加此规则所依赖的规则)。每个目录都会由依赖于此规则的 py_binary 规则添加到 PYTHONPATH 中。

不允许使用绝对路径(以 / 开头的路径)和引用执行根目录上方的路径,否则会导致错误。

legacy_create_init

Integer; optional; default is -1

是否在 runfiles 树中隐式创建空的 __init__.py 文件。 这些代码库是在包含 Python 源代码或共享库的每个目录以及这些目录的每个父目录(不包括 Repo 根目录)中创建的。默认值为“true”,除非使用 --incompatible_default_to_explicit_init_py。如果为 false,则用户负责创建(可能为空)__init__.py 文件并根据需要将该文件添加到 Python 目标的 srcs 中。
main

Label; optional

作为应用主要入口点的源文件的名称。 此文件还必须在 srcs 中列出。如果未指定,则改用 name(见上文)。如果 namesrcs 中的任何文件名都不匹配,则必须指定 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 的值。如需了解详情,请参阅此处

bug 警告:此属性设置 Bazel 构建目标的版本,但由于 #4815,生成的存根脚本可能仍会在运行时调用错误的解释器版本。请参阅此权宜解决方法,其中涉及定义指向所需 Python 版本的 py_runtime 目标,并根据需要通过设置 --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

是否将 build 信息编码到二进制文件中。可能的值包括:
  • stamp = 1:始终将 build 信息印入二进制文件,即使在 --nostamp build 中也是如此。应避免此设置,因为它可能会终止二进制文件的远程缓存以及任何依赖于它的下游操作。
  • stamp = 0:始终使用常量值替换 build 信息。这样可以提供良好的构建结果缓存。
  • stamp = -1:build 信息的嵌入由 --[no]stamp 标志控制。

除非依赖项发生变化,否则系统不会重建 build 二进制文件。

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 的导入目录列表。

“使变量”为替代项。系统会为此规则以及与其关联的所有规则添加这些导入目录(注意:不会添加此规则所依赖的规则)。每个目录都会由依赖于此规则的 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 的导入目录列表。

“使变量”为替代项。系统会为此规则以及与其关联的所有规则添加这些导入目录(注意:不会添加此规则所依赖的规则)。每个目录都会由依赖于此规则的 py_binary 规则添加到 PYTHONPATH 中。

不允许使用绝对路径(以 / 开头的路径)和引用执行根目录上方的路径,否则会导致错误。

legacy_create_init

Integer; optional; default is -1

是否在 runfiles 树中隐式创建空的 __init__.py 文件。 这些代码库是在包含 Python 源代码或共享库的每个目录以及这些目录的每个父目录(不包括 Repo 根目录)中创建的。默认值为“true”,除非使用 --incompatible_default_to_explicit_init_py。如果为 false,则用户负责创建(可能为空)__init__.py 文件并根据需要将该文件添加到 Python 目标的 srcs 中。
main

Label; optional

作为应用主要入口点的源文件的名称。 此文件还必须在 srcs 中列出。如果未指定,则改用 name(见上文)。如果 namesrcs 中的任何文件名都不匹配,则必须指定 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 的值。如需了解详情,请参阅此处

bug 警告:此属性设置 Bazel 构建目标的版本,但由于 #4815,生成的存根脚本可能仍会在运行时调用错误的解释器版本。请参阅此权宜解决方法,其中涉及定义指向所需 Python 版本的 py_runtime 目标,并根据需要通过设置 --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() 参数的部分,不过,对于测试,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

Name; required

此目标的唯一名称。

bootstrap_template

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

以前称为“Python 桩脚本”,它是每个 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 解释器的绝对路径。对于 build 运行时,不得设置此属性。
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"

在执行 py_binary 目标时使用的引导式 Python 脚本之前加上“Shebang”表达式。

请参阅问题 8685,了解实际情况。

不适用于 Windows。