报告问题open_in_new
查看源代码open_in_new
每晚
·
7.3。
·
7.2。
·
7.1。
·
7.0。
·
6.5
规则
py_binary
查看规则来源open_in_new
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”
依赖于此规则该字符串是 repo-runfiles-root 相对字符串，
绝对路径（以 `/` 开头的路径）和引用某个路径的路径
高于执行根目录，则会导致错误。
|
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
|
String;默认值为 "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()` 函数的
位于 https://docs.python.org/3/library/functions.html#compile 的 `optimize` 参数文档
注意：值“-1”表示“当前解释器”，也就是解释器
在 _在构建 pycs 时_ 使用，而不是在
在代码实际运行时运行
|
precompile_source_retention
|
String;默认值为 "inherit"
确定在编译源文件时是否保留源文件
对输出结果的影响。有效值包括：
* `inherit`：从 {flag}`--precompile_source_retention` 标志继承值。
* `keep_source`：包含原始 Python 源代码。
* `omit_source`：请勿包含原始 py 源代码。
* `omit_if_generated_source`：如果是常规来源，则保留原始来源
文件；但如果是生成的文件，则将其省略。
|
pyc_collection
|
String;默认值为 "inherit"
确定是否应手动包含依赖项中的 pyc 文件。
注意：此设置仅适用于 {flag}`--precompile_add_to_runfiles=decided_elsewhere`。
有效值：
* `inherit`：从 {flag}`--pyc_collection` 继承值。
* `include_pyc`：将二进制文件中的依赖项中的 pyc 文件添加到 {obj}`PyInfo.transitive_pyc_files`。
* `disabled`：不从依赖项中显式添加 pyc 文件。请注意，
如果目标包含依赖项的 pyc 文件，则它们可能仍来自依赖项
的一部分（例如，当 {obj}`--precompile_add_to_runfiles=always` 时
）。
|
python_version
|
字符串；默认值为 "PY3"
已废弃，未使用，不执行任何操作。
|
srcs_version
|
String;默认值为 "PY2AND3"
已废弃，未使用，不执行任何操作。
|
stamp
|
Integer;默认值为 -1
是否将 build 信息编码到二进制文件中。可能的值：
* `stamp = 1`：始终将 build 信息戳记到二进制文件中，即使在 `--nostamp` build 中也是如此。**应避免使用此设置**，因为它可能会终止二进制文件以及依赖于它的所有下游操作的远程缓存。* `stamp = 0`：始终将 build 信息替换为常量值。这样可以实现良好的 build 结果缓存。* `stamp = -1`：构建信息的嵌入由
`--[no]stamp` 标志。
除非其依赖项发生变化，否则系统不会重新构建带有标记的二进制文件。
警告：加盖章可能会降低缓存命中率，从而影响 build 性能，因此应尽可能避免。
|
py_library
查看规则源代码open_in_new
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 源
* 源代码中的预编译工件。
注意：预编译会影响
生成的 runfile。如需了解详情，请参阅与预编译相关的属性和标志。
参数
| 属性 |
name |
姓名；必需
此目标的唯一名称。
|
deps
|
标签列表；默认值为 []
要链接到目标中的其他库的列表。查看相关评论
[`deps` 属性通常由
rules](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 的导入目录列表。
受“创建变量”约束替换。系统会为此规则以及依赖于它的所有规则添加这些导入目录（注意：不是此规则依赖的规则）。每个目录都将通过“py_binary”规则添加到“PYTHONPATH”
依赖于此规则该字符串是 repo-runfiles-root 相对字符串，
绝对路径（以 `/` 开头的路径）和引用某个路径的路径
高于执行根目录，则会导致错误。
|
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()` 函数的
位于 https://docs.python.org/3/library/functions.html#compile 的 `optimize` 参数文档
注意：值“-1”表示“当前解释器”，也就是解释器
在 _在构建 pycs 时_ 使用，而不是在
在代码实际运行时运行
|
precompile_source_retention
|
String;默认值为 "inherit"
确定在编译源文件时是否保留源文件
对输出结果的影响。有效值包括：
* `inherit`：从 {flag}`--precompile_source_retention` 标志继承值。
* `keep_source`：包含原始 Python 源代码。
* `omit_source`：不添加原始 py 源代码。
* `omit_if_generated_source`：如果是常规来源，则保留原始来源
文件；但如果是生成的文件，则将其省略。
|
srcs_version
|
String;默认值为 "PY2AND3"
不存在、未使用、不会执行任何操作。
|
py_test
查看规则源代码open_in_new
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` 属性通常由
rules](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)。
没有像 `cc_embed_data` 和 `go_embed_data` 一样的 `py_embed_data`。
这是因为 Python 有一个运行时资源的概念。
|
imports
|
字符串列表；默认值为 []
要添加到 PYTHONPATH 的导入目录的列表。
需遵循“Make 变量”替换规则。系统会为此规则以及依赖于它的所有规则添加这些导入目录（注意：不是此规则依赖的规则）。每个目录都将通过“py_binary”规则添加到“PYTHONPATH”
依赖于此规则该字符串是 repo-runfiles-root 相对字符串，
绝对路径（以 `/` 开头的路径）和引用某个路径的路径
高于执行根目录，则会导致错误。
|
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
|
String;默认值为 "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()` 函数的
位于 https://docs.python.org/3/library/functions.html#compile 的 `optimize` 参数文档
注意：值“-1”表示“当前解释器”，也就是解释器
在 _在构建 pycs 时_ 使用，而不是在
在代码实际运行时运行
|
precompile_source_retention
|
String;默认值为 "inherit"
确定在编译源文件时是否保留源文件
对输出结果的影响。有效值包括：
* `inherit`：从 {flag}`--precompile_source_retention` 标志继承值。
* `keep_source`：包含原始 Python 源代码。
* `omit_source`：请勿包含原始 py 源代码。
* `omit_if_generated_source`：如果是常规来源，则保留原始来源
文件；但如果是生成的文件，则将其省略。
|
pyc_collection
|
String;默认值为 "inherit"
确定是否应手动包含依赖项中的 pyc 文件。
注意：此设置仅适用于 {flag}`--precompile_add_to_runfiles=decided_elsewhere`。
有效值：
* `inherit`：从 {flag}`--pyc_collection` 继承值。
* `include_pyc`：将二进制文件中的依赖项中的 pyc 文件添加到 {obj}`PyInfo.transitive_pyc_files`。
* `disabled`：不从依赖项中显式添加 pyc 文件。请注意，
如果目标包含依赖项的 pyc 文件，则它们可能仍来自依赖项
的一部分（例如，当 {obj}`--precompile_add_to_runfiles=always` 时
）。
|
python_version
|
字符串；默认值为 "PY3"
已废弃，未使用，不执行任何操作。
|
srcs_version
|
String;默认值为 "PY2AND3"
不存在、未使用、不会执行任何操作。
|
stamp
|
Integer;默认值为 0
是否将 build 信息编码到二进制文件中。可能的值：
* `stamp = 1`：始终将 build 信息印到二进制文件中，即使在
`--nostamp` 构建。**应避免使用此设置**，因为它可能会终止二进制文件以及依赖于它的所有下游操作的远程缓存。* `stamp = 0`：始终将 build 信息替换为常量值。如此一来，
良好的构建结果缓存
* `stamp = -1`：构建信息的嵌入由
`--[no]stamp` 标志。
除非其依赖项发生变化，否则系统不会重新构建带有标记的二进制文件。
警告：加盖章可能会降低缓存命中率，从而影响 build 性能，因此应尽可能避免。
|
py_runtime
查看规则来源open_in_new
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 中
runtime*。平台运行时以已知的
而构建运行时指向可执行目标
翻译。在这两种情况下，“口译员”指任何可执行二进制文件或
能够运行通过命令传递的 Python 脚本的封装容器脚本
行，遵循与标准 CPython 解释器相同的约定。
平台运行时本质上是非密封的。它要求目标平台将解释器放置在特定路径中。构建时运行时可以是或不是密封的，具体取决于它是指向已签入的解释器还是指向访问系统解释器的封装容器脚本。
示例
```
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
这是一个目标，用于从 Cloud Storage 中收集代码覆盖率信息
{rule}`py_binary` 和 {rule}`py_test` 目标。
如果设置，目标必须生成单个文件或成为可执行目标。
单个文件的路径；如果目标可执行，则为可执行文件的路径；
确定 python 覆盖率工具的入口点。目标及其
启用覆盖率功能后，系统会将 runfiles 添加到 runfile 中。
工具的入口点必须可供 Python 解释器加载（例如 `.py` 或 `.pyc` 文件）。它必须接受命令行参数
的 [`coverage.py`](https://coverage.readthedocs.io)，至少包括
“run”和“lcov”子命令
|
files
|
标签列表；默认值为 []
对于构建运行时，这是包含此运行时的一组文件。
这些文件将添加到使用此运行时的 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
|
String;默认值为 ""
对于平台运行时，这是 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。如果未指定，则将进行计算
。如果没有 pyc_tag
则只有无来源 pyc 生成才能正常运行。
|
python_version
|
String;默认值为 "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"
“Shebang”附加到引导 Python 桩脚本前面的表达式
在执行 {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` 字段。
:::
|
