Python 规则

报告问题 查看源代码 每夜 build · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

规则

• 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, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, python_version, restricted_to, srcs_version, stamp, tags, target_compatible_with, testonly, toolchains, visibility)

参数

属性
name	名称；必需 此目标的唯一名称。
deps	标签列表；默认值为 [] 要链接到目标中的其他库的列表。请参阅有关 [`deps` 属性（通常由规则定义）](https://bazel.build/reference/be/common-definitions#typical-attributes) 的评论。这些通常是 `py_library` 规则。 仅提供运行时使用的文件的目标属于 `data` 属性。
srcs	标签列表；必需 用于创建目标的经过处理的 Python 源文件列表。这包括您已提交的所有代码，并且可能包括生成的源文件。`.py` 文件属于 `srcs`，库目标属于 `deps`。运行时可能需要的其他二进制文件属于 `data`。
data	标签列表；默认值为 [] 此库在运行时需要的文件列表。请参阅有关 [`data` 属性（通常由规则定义）](https://bazel.build/reference/be/common-definitions#typical-attributes)的评论。 没有 `py_embed_data`，而有 `cc_embed_data` 和 `go_embed_data`。这是因为 Python 有运行时资源的概念。
imports	字符串列表；默认值为 [] 要添加到 PYTHONPATH 的导入目录列表。 需遵循“Make 变量”替换规则。系统会为此规则以及依赖于它的所有规则添加这些导入目录（注意：不是此规则依赖的规则）。每个目录都将由依赖于此规则的 `py_binary` 规则添加到 `PYTHONPATH`。这些字符串相对于代码库运行文件根目录，不允许使用绝对路径（以“/”开头的路径）和引用执行根目录上方路径的路径，否则会导致错误。
legacy_create_init	整数；默认为 -1 是否在 runfiles 树中隐式创建空的 `__init__.py` 文件。这些文件会在包含 Python 源代码或共享库的每个目录以及这些目录的每个父目录（代码库根目录除外）中创建。默认值“-1”（自动）表示 true，除非使用 `--incompatible_default_to_explicit_init_py`。如果为 false，用户负责创建（可能为空的）`__init__.py` 文件，并根据需要将其添加到 Python 目标的 `srcs`。
main	标签；默认值为 None 可选；是应用的主要入口点的源文件的名称。此文件还必须列在 `srcs` 中。如果未指定，系统会改为使用附加 `.py` 的 `name`。如果 `name` 与 `srcs` 中的任何文件名都不匹配，则必须指定 `main`。
precompile	字符串；默认值为 "inherit" 是否应预编译 **此目标** 的 py 源文件。 值： * `inherit`：根据 {flag}`--precompile` 标志确定值。 * `enabled`：在构建时编译 Python 源文件。请注意，--precompile_add_to_runfiles 会影响编译后的文件被纳入下游二进制文件的方式。* `disabled`：在构建时不编译 Python 源文件。* `if_generated_source`：编译 Python 源文件，但仅当它们是生成的文件时才编译。 :::{seealso} * {flag}`--precompile` 标志，在某些情况下可以替换此属性，并且会在构建时影响所有目标。 * {obj}`pyc_collection` 属性，用于以传递方式按目标启用预编译。* [预编译](precompiling) 文档，其中包含有关使用预编译的指南。 :::
precompile_invalidation_mode	字符串；默认值为 "auto" 如何验证预编译文件是否与其关联的源文件保持最新状态。可能的值包括： * `auto`：有效值将由其他 build 设置自动确定。 * `checked_hash`：如果源文件的哈希与 pyc 文件中记录的哈希相符，则使用 pyc 文件。在处理可能要修改的代码时，此功能最为有用。* `unchecked_hash`：始终使用 pyc 文件；不要将 pyc 的哈希与源文件进行比较。当代码不会被修改时，这种方法最有用。 如需详细了解 pyc 失效模式，请参阅 https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode
precompile_optimize_level	整数；默认为 0 预编译文件的优化级别。 如需详细了解优化级别，请参阅 `compile()` 函数的 `optimize` 参数文档 (https://docs.python.org/3/library/functions.html#compile) 注意：值 `-1` 表示“当前解释器”，即在生成 pyc 的构建时使用的解释器，而不是在代码实际运行时运行时使用的解释器。
precompile_source_retention	字符串；默认值为 "inherit" 确定在编译源文件时，源文件是否保留在生成的输出中。有效值包括： * `inherit`：从 {flag}`--precompile_source_retention` 标志继承值。 * `keep_source`：包含原始 Python 源代码。 * `omit_source`：不添加原始 py 源代码。 * `omit_if_generated_source`：如果原始源代码是常规源代码文件，则保留该源代码；如果原始源代码是生成的文件，则忽略该源代码。
pyc_collection	字符串；默认值为 "inherit" 确定是否应手动添加依赖项中的 pyc 文件。 注意：此设置仅适用于 {flag}`--precompile_add_to_runfiles=decided_elsewhere`。 有效值： * `inherit`：从 {flag}`--pyc_collection` 继承值。 * `include_pyc`：将二进制文件中的依赖项中的 pyc 文件添加到 {obj}`PyInfo.transitive_pyc_files`。 * `disabled`：不从依赖项中显式添加 pyc 文件。请注意，如果目标将 pyc 文件作为其 runfile 的一部分包含在内（例如使用 {obj}`--precompile_add_to_runfiles=always` 时），这些文件可能仍来自依赖项。
python_version	字符串；默认值为 "PY3" 已废弃，未使用，不执行任何操作。
srcs_version	字符串；默认值为 "PY2AND3" 已废弃，未使用，不执行任何操作。
stamp	整数；默认为 -1 是否将 build 信息编码到二进制文件中。可能的值： * `stamp = 1`：始终将 build 信息戳记到二进制文件中，即使在 `--nostamp` build 中也是如此。**应避免使用此设置**，因为它可能会终止二进制文件以及依赖于它的所有下游操作的远程缓存。* `stamp = 0`：始终将 build 信息替换为常量值。这样可以实现良好的 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, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, restricted_to, srcs_version, tags, target_compatible_with, testonly, toolchains, visibility)

可依赖的 Python 代码库。 默认输出： * 输入 Python 源代码 * 源代码中的预编译工件。 注意：预编译会影响最终运行文件中包含哪些默认输出。如需了解详情，请参阅与预编译相关的属性和标志。

参数

属性
name	名称；必需 此目标的唯一名称。
deps	标签列表；默认值为 [] 要链接到目标中的其他库的列表。请参阅有关 [`deps` 属性（通常由规则定义）](https://bazel.build/reference/be/common-definitions#typical-attributes) 的评论。这些通常是 `py_library` 规则。 仅提供运行时使用的文件的目标属于 `data` 属性。
srcs	标签列表；默认值为 [] 用于创建目标的经过处理的 Python 源文件列表。这包括您已提交的所有代码，并且可能包括生成的源文件。`.py` 文件属于 `srcs`，库目标属于 `deps`。运行时可能需要的其他二进制文件属于 `data`。
data	标签列表；默认值为 [] 此库在运行时需要的文件列表。请参阅有关 [`data` 属性（通常由规则定义）](https://bazel.build/reference/be/common-definitions#typical-attributes)的评论。 没有 `py_embed_data`，而有 `cc_embed_data` 和 `go_embed_data`。这是因为 Python 有运行时资源的概念。
imports	字符串列表；默认值为 [] 要添加到 PYTHONPATH 的导入目录列表。 需遵循“Make 变量”替换规则。系统会为此规则以及依赖于它的所有规则添加这些导入目录（注意：不是此规则依赖的规则）。每个目录都将由依赖于此规则的 `py_binary` 规则添加到 `PYTHONPATH`。这些字符串相对于代码库运行文件根目录，不允许使用绝对路径（以“/”开头的路径）和引用执行根目录上方路径的路径，否则会导致错误。
precompile	字符串；默认值为 "inherit" 是否应预编译 **此目标** 的 py 源文件。 值： * `inherit`：根据 {flag}`--precompile` 标志确定值。 * `enabled`：在构建时编译 Python 源文件。请注意，--precompile_add_to_runfiles 会影响编译后的文件被纳入下游二进制文件的方式。* `disabled`：在构建时不编译 Python 源文件。* `if_generated_source`：编译 Python 源文件，但仅当它们是生成的文件时才编译。 :::{seealso} * {flag}`--precompile` 标志，在某些情况下可以替换此属性，并且会在构建时影响所有目标。 * {obj}`pyc_collection` 属性，用于以传递方式按目标启用预编译。* [预编译](precompiling) 文档，其中包含有关使用预编译的指南。 :::
precompile_invalidation_mode	字符串；默认值为 "auto" 如何验证预编译文件是否与其关联的源文件保持最新状态。可能的值包括： * `auto`：有效值将由其他 build 设置自动确定。 * `checked_hash`：如果源文件的哈希与 pyc 文件中记录的哈希相符，则使用 pyc 文件。在处理可能要修改的代码时，此功能最为有用。* `unchecked_hash`：始终使用 pyc 文件；不要将 pyc 的哈希与源文件进行比较。当代码不会被修改时，这种方法最有用。 如需详细了解 pyc 失效模式，请参阅 https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode
precompile_optimize_level	整数；默认为 0 预编译文件的优化级别。 如需详细了解优化级别，请参阅 `compile()` 函数的 `optimize` 参数文档 (https://docs.python.org/3/library/functions.html#compile) 注意：值 `-1` 表示“当前解释器”，即在生成 pyc 的构建时使用的解释器，而不是在代码实际运行时运行时使用的解释器。
precompile_source_retention	字符串；默认值为 "inherit" 确定在编译源文件时，源文件是否保留在生成的输出中。有效值包括： * `inherit`：从 {flag}`--precompile_source_retention` 标志继承值。 * `keep_source`：包含原始 Python 源代码。 * `omit_source`：不添加原始 py 源代码。 * `omit_if_generated_source`：如果原始源代码是常规源代码文件，则保留该源代码；如果原始源代码是生成的文件，则忽略该源代码。
srcs_version	字符串；默认值为 "PY2AND3" 已废弃，未使用，不执行任何操作。

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, precompile, precompile_invalidation_mode, precompile_optimize_level, precompile_source_retention, pyc_collection, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility)

参数

属性
name	名称；必需 此目标的唯一名称。
deps	标签列表；默认值为 [] 要链接到目标中的其他库的列表。请参阅有关 [`deps` 属性（通常由规则定义）](https://bazel.build/reference/be/common-definitions#typical-attributes) 的评论。这些通常是 `py_library` 规则。 仅提供运行时使用的文件的目标属于 `data` 属性。
srcs	标签列表；必需 用于创建目标的经过处理的 Python 源文件列表。这包括您已提交的所有代码，并且可能包括生成的源文件。`.py` 文件属于 `srcs`，库目标属于 `deps`。运行时可能需要的其他二进制文件属于 `data`。
data	标签列表；默认值为 [] 此库在运行时需要的文件列表。请参阅有关 [`data` 属性（通常由规则定义）](https://bazel.build/reference/be/common-definitions#typical-attributes)的评论。 没有 `py_embed_data`，而有 `cc_embed_data` 和 `go_embed_data`。这是因为 Python 有运行时资源的概念。
imports	字符串列表；默认值为 [] 要添加到 PYTHONPATH 的导入目录列表。 需遵循“Make 变量”替换规则。系统会为此规则以及依赖于它的所有规则添加这些导入目录（注意：不是此规则依赖的规则）。每个目录都将由依赖于此规则的 `py_binary` 规则添加到 `PYTHONPATH`。这些字符串相对于代码库运行文件根目录，不允许使用绝对路径（以“/”开头的路径）和引用执行根目录上方路径的路径，否则会导致错误。
legacy_create_init	整数；默认为 -1 是否在 runfiles 树中隐式创建空的 `__init__.py` 文件。这些文件会在包含 Python 源代码或共享库的每个目录以及这些目录的每个父目录（代码库根目录除外）中创建。默认值“-1”（自动）表示 true，除非使用 `--incompatible_default_to_explicit_init_py`。如果为 false，用户负责创建（可能为空的）`__init__.py` 文件，并根据需要将其添加到 Python 目标的 `srcs`。
main	标签；默认值为 None 可选；是应用的主要入口点的源文件的名称。此文件还必须列在 `srcs` 中。如果未指定，系统会改为使用附加 `.py` 的 `name`。如果 `name` 与 `srcs` 中的任何文件名都不匹配，则必须指定 `main`。
precompile	字符串；默认值为 "inherit" 是否应预编译 **此目标** 的 py 源文件。 值： * `inherit`：根据 {flag}`--precompile` 标志确定值。 * `enabled`：在构建时编译 Python 源文件。请注意，--precompile_add_to_runfiles 会影响编译后的文件被纳入下游二进制文件的方式。* `disabled`：在构建时不编译 Python 源文件。* `if_generated_source`：编译 Python 源文件，但仅当它们是生成的文件时才编译。 :::{seealso} * {flag}`--precompile` 标志，在某些情况下可以替换此属性，并且会在构建时影响所有目标。 * {obj}`pyc_collection` 属性，用于以传递方式按目标启用预编译。* [预编译](precompiling) 文档，其中包含有关使用预编译的指南。 :::
precompile_invalidation_mode	字符串；默认值为 "auto" 如何验证预编译文件是否与其关联的源文件保持最新状态。可能的值包括： * `auto`：有效值将由其他 build 设置自动确定。 * `checked_hash`：如果源文件的哈希与 pyc 文件中记录的哈希相符，则使用 pyc 文件。在处理可能要修改的代码时，此功能最为有用。* `unchecked_hash`：始终使用 pyc 文件；不要将 pyc 的哈希与源文件进行比较。当代码不会被修改时，这种方法最有用。 如需详细了解 pyc 失效模式，请参阅 https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode
precompile_optimize_level	整数；默认为 0 预编译文件的优化级别。 如需详细了解优化级别，请参阅 `compile()` 函数的 `optimize` 参数文档 (https://docs.python.org/3/library/functions.html#compile) 注意：值 `-1` 表示“当前解释器”，即在生成 pyc 的构建时使用的解释器，而不是在代码实际运行时运行时使用的解释器。
precompile_source_retention	字符串；默认值为 "inherit" 确定在编译源文件时，源文件是否保留在生成的输出中。有效值包括： * `inherit`：从 {flag}`--precompile_source_retention` 标志继承值。 * `keep_source`：包含原始 Python 源代码。 * `omit_source`：不添加原始 py 源代码。 * `omit_if_generated_source`：如果原始源代码是常规源代码文件，则保留该源代码；如果原始源代码是生成的文件，则忽略该源代码。
pyc_collection	字符串；默认值为 "inherit" 确定是否应手动添加依赖项中的 pyc 文件。 注意：此设置仅适用于 {flag}`--precompile_add_to_runfiles=decided_elsewhere`。 有效值： * `inherit`：从 {flag}`--pyc_collection` 继承值。 * `include_pyc`：将二进制文件中的依赖项中的 pyc 文件添加到 {obj}`PyInfo.transitive_pyc_files`。 * `disabled`：不从依赖项中显式添加 pyc 文件。请注意，如果目标将 pyc 文件作为其 runfile 的一部分包含在内（例如使用 {obj}`--precompile_add_to_runfiles=always` 时），这些文件可能仍来自依赖项。
python_version	字符串；默认值为 "PY3" 已废弃，未使用，不执行任何操作。
srcs_version	字符串；默认值为 "PY2AND3" 已废弃，未使用，不执行任何操作。
stamp	整数；默认为 0 是否将 build 信息编码到二进制文件中。可能的值： * `stamp = 1`：始终将 build 信息戳记到二进制文件中，即使在 `--nostamp` build 中也是如此。**应避免使用此设置**，因为它可能会终止二进制文件以及依赖于它的所有下游操作的远程缓存。* `stamp = 0`：始终将 build 信息替换为常量值。这样可以实现良好的 build 结果缓存。* `stamp = -1`：build 信息的嵌入由 `--[no]stamp` 标志控制。 除非其依赖项发生变化，否则系统不会重新构建带有标记的二进制文件。 警告：加盖章可能会降低缓存命中率，从而影响 build 性能，因此应尽可能避免。

py_runtime

查看规则源代码

py_runtime(name, bootstrap_template, compatible_with, coverage_tool, deprecation, distribs, exec_compatible_with, exec_properties, features, files, implementation_name, interpreter, interpreter_path, interpreter_version_info, pyc_tag, python_version, restricted_to, stage2_bootstrap_template, stub_shebang, tags, target_compatible_with, testonly, toolchains, visibility, zip_main_template)

表示用于执行 Python 代码的 Python 运行时。 `py_runtime` 目标可以表示 *平台运行时* 或 *build 内运行时*。平台运行时会访问已知路径中的系统安装的解释器，而内置运行时会指向用作解释器的可执行目标。在这两种情况下，“解释器”都表示能够按照与标准 CPython 解释器相同的惯例，运行通过命令行传递的 Python 脚本的任何可执行二进制文件或封装容器脚本。 平台运行时本质上是非密封的。它要求目标平台将解释器放置在特定路径中。构建时运行时可以是或不是密封的，具体取决于它是指向已签入的解释器还是指向访问系统解释器的封装容器脚本。 示例 ``` load("@rules_python//python:py_runtime.bzl", "py_runtime") 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	标签；默认值为 "@rules_python//python/private:bootstrap_template" 要使用的引导脚本模板文件。应包含 %python_binary%、%workspace_name%、%main% 和 %imports%。 此模板在展开后会成为用于启动进程的可执行文件，因此它负责执行初始引导操作，例如查找 Python 解释器、runfile 和构建用于运行预期 Python 应用的环境。 虽然此属性目前是可选属性，但当 Python 规则从 Bazel 本身移出后，它将变为必需属性。 展开后的确切变量名称是一个不稳定的 API，可能会发生变化。 将 Python 规则移出 Bazel 本身后，该 API 将变得更加稳定。 如需了解更多变量，请参阅 @bazel_tools//tools/python:python_bootstrap_template.txt。
coverage_tool	标签；默认值为 None 此目标用于从 {rule}`py_binary` 和 {rule}`py_test` 目标收集代码覆盖率信息。 如果设置了此属性，目标必须生成单个文件，或者是可执行目标。单个文件的路径（如果目标是可执行文件，则为可执行文件的路径）决定了 Python 覆盖率工具的入口点。启用代码覆盖率后，目标及其 runfile 将添加到 runfile 中。 工具的入口点必须可供 Python 解释器加载（例如 `.py` 或 `.pyc` 文件）。它必须接受 [`coverage.py`](https://coverage.readthedocs.io) 的命令行参数，至少包括 `run` 和 `lcov` 子命令。
files	标签列表；默认值为 [] 对于 build 内运行时，这是构成此运行时的一组文件。这些文件将添加到使用此运行时的 Python 二进制文件的 runfile 中。对于平台运行时，不得设置此属性。
implementation_name	字符串；默认值为 "" Python 实现名称 (`sys.implementation.name`)
interpreter	标签；默认值为 None 对于 build 内运行时，这是要作为解释器调用的目标。它可以是以下任一项： * 单个文件，即解释器二进制文件。假定此类解释器是自包含的单文件可执行文件，或者在 `files` 中指定了任何支持文件。 * 可执行目标。目标的可执行文件将是解释器二进制文件。 系统会自动包含任何其他默认输出 (`target.files`) 和普通文件 runfile (`runfiles.files`)，就像在 `files` 属性中指定一样。 注意：目标的 runfile 可能尚未正确遵循/传播到工具链/解释器的使用方，请参阅 bazelbuild/rules_python/issues/1612。对于平台运行时（即设置了 `interpreter_path`），不得设置此属性。
interpreter_path	字符串；默认值为 "" 对于平台运行时，这是目标平台上 Python 解释器的绝对路径。对于 build 内运行时，不得设置此属性。
interpreter_version_info	字典：字符串 -> 字符串；默认值为 {} 此运行时提供的解释器的版本信息。 如果未指定，则使用 {obj}`--python_version` 支持的键与 `sys.version_info` 的名称匹配。虽然输入值是字符串，但大多数会转换为整数。支持的键包括： * major：int，主要版本号 * minor：int，次要版本号 * micro：可选 int，微版本号 * releaselevel：可选 str，版本级别 * serial：可选 int，版本的序列号 :::{versionchanged} 0.36.0 {obj}`--python_version` 决定默认值。 :::
pyc_tag	字符串；默认值为 "" 可选字符串；pyc 文件名的标记部分，例如 `foo.cpython-39.pyc` 中的 `cpython-39` 中缀。请参阅 PEP 3147。如果未指定，系统会根据 `implementation_name` 和 `interpreter_version_info` 计算此值。如果没有可用的 pyc_tag，则只有无源代码的 pyc 生成功能才能正常运行。
python_version	字符串；默认值为 "PY3" 此运行时是否适用于 Python 主要版本 2 或 3。有效值为 `"PY2"` 和 `"PY3"`。默认值由 `--incompatible_py3_is_default` 标志控制。不过，将来此属性将是必需属性，且没有默认值。
stage2_bootstrap_template	标签；默认值为 "@rules_python//python/private:stage2_bootstrap_template" 启用两阶段引导时要使用的模板 :::{seealso} {obj}`PyRuntimeInfo.stage2_bootstrap_template` 和 {obj}`--bootstrap_impl` :::
stub_shebang	字符串；默认值为 "#!/usr/bin/env python3" 附加到引导 Python 桩脚本的“shebang”表达式，用于执行 {rule}`py_binary` 目标。 如需了解具体原因，请参阅 https://github.com/bazelbuild/bazel/issues/8685。 不适用于 Windows。
zip_main_template	标签；默认值为 "@rules_python//python/private:zip_main_template" 要用于 ZIP 文件顶级 `__main__.py` 文件的模板。 这将成为运行 `python foo.zip` 时执行的入口点。 :::{seealso} {obj}`PyRuntimeInfo.zip_main_template` 字段。 :::