| <html devsite> | |
| <head> | |
| <meta name="project_path" value="/_project.yaml"> | |
| <meta name="book_path" value="/versions/8.3.0/_book.yaml"> | |
| </head> | |
| <body> | |
| <!-- | |
| This document is synchronized with Bazel releases. | |
| To edit, submit changes to the Bazel source code. | |
| --> | |
| <!-- Generated by //src/main/java/com/google/devtools/build/docgen:build-encyclopedia.zip --> | |
| <html> | |
| <body> | |
| <h1 class="page-title">Python Rules</h1> | |
| {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} | |
| {% dynamic setvar version "8.3.0" %} | |
| {% dynamic setvar original_path "/reference/be/python" %} | |
| {% include "_buttons.html" %} | |
| <h2>Rules</h2> | |
| <ul> | |
| <li> | |
| <a href="#py_binary"> | |
| py_binary </a> | |
| </li> | |
| <li> | |
| <a href="#py_library"> | |
| py_library </a> | |
| </li> | |
| <li> | |
| <a href="#py_test"> | |
| py_test </a> | |
| </li> | |
| <li> | |
| <a href="#py_runtime"> | |
| py_runtime </a> | |
| </li> | |
| </ul> | |
| <h2 id="py_binary"> | |
| py_binary | |
| </h2> | |
| <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_binary_rule.bzl" target="_blank"> | |
| View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> | |
| </a> | |
| <pre class="rule-signature">py_binary(<a href="#py_binary.name">name</a>, <a href="#py_binary.deps">deps</a>, <a href="#py_binary.srcs">srcs</a>, <a href="#py_binary.data">data</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#binary.env">env</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#py_binary.imports">imports</a>, <a href="#py_binary.legacy_create_init">legacy_create_init</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#py_binary.main">main</a>, <a href="common-definitions.html#binary.output_licenses">output_licenses</a>, <a href="#py_binary.precompile">precompile</a>, <a href="#py_binary.precompile_invalidation_mode">precompile_invalidation_mode</a>, <a href="#py_binary.precompile_optimize_level">precompile_optimize_level</a>, <a href="#py_binary.precompile_source_retention">precompile_source_retention</a>, <a href="#py_binary.pyc_collection">pyc_collection</a>, <a href="#py_binary.python_version">python_version</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#py_binary.srcs_version">srcs_version</a>, <a href="#py_binary.stamp">stamp</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> | |
| <h3 id="py_binary_args">Arguments</h3> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th colspan="2">Attributes</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="py_binary.name"><code>name</code></td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels#target-names">Name</a>; required</p> | |
| <p>A unique name for this target.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.deps"> | |
| <code>deps</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/8.3.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| List of additional libraries to be linked in to the target. | |
| See comments about | |
| the [`deps` attribute typically defined by | |
| rules](https://bazel.build/reference/be/common-definitions#typical-attributes). | |
| These are typically `py_library` rules. | |
| Targets that only provide data files used at runtime belong in the `data` | |
| attribute. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.srcs"> | |
| <code>srcs</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/8.3.0/concepts/labels">labels</a>; required</p> | |
| The list of Python source files that are processed to create the target. This | |
| includes all your checked-in code and may include generated source files. The | |
| `.py` files belong in `srcs` and library targets belong in `deps`. Other binary | |
| files that may be needed at run time belong in `data`. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.data"> | |
| <code>data</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/8.3.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| The list of files need by this library at runtime. See comments about | |
| the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). | |
| There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. | |
| This is because Python has a concept of runtime resources. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.imports"> | |
| <code>imports</code> | |
| </td> | |
| <td> | |
| <p>List of strings; default is <code>[]</code></p> | |
| List of import directories to be added to the PYTHONPATH. | |
| Subject to "Make variable" substitution. These import directories will be added | |
| for this rule and all rules that depend on it (note: not the rules this rule | |
| depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules | |
| that depend on this rule. The strings are repo-runfiles-root relative, | |
| Absolute paths (paths that start with `/`) and paths that references a path | |
| above the execution root are not allowed and will result in an error. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.legacy_create_init"> | |
| <code>legacy_create_init</code> | |
| </td> | |
| <td> | |
| <p>Integer; default is <code>-1</code></p> | |
| Whether to implicitly create empty `__init__.py` files in the runfiles tree. | |
| These are created in every directory containing Python source code or shared | |
| libraries, and every parent directory of those directories, excluding the repo | |
| root directory. The default, `-1` (auto), means true unless | |
| `--incompatible_default_to_explicit_init_py` is used. If false, the user is | |
| responsible for creating (possibly empty) `__init__.py` files and adding them to | |
| the `srcs` of Python targets as required. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.main"> | |
| <code>main</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels">Label</a>; default is <code>None</code></p> | |
| Optional; the name of the source file that is the main entry point of the | |
| application. This file must also be listed in `srcs`. If left unspecified, | |
| `name`, with `.py` appended, is used instead. If `name` does not match any | |
| filename in `srcs`, `main` must be specified. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.precompile"> | |
| <code>precompile</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"inherit"</code></p> | |
| Whether py source files **for this target** should be precompiled. | |
| Values: | |
| * `inherit`: Allow the downstream binary decide if precompiled files are used. | |
| * `enabled`: Compile Python source files at build time. | |
| * `disabled`: Don't compile Python source files at build time. | |
| :::{seealso} | |
| * The {flag}`--precompile` flag, which can override this attribute in some cases | |
| and will affect all targets when building. | |
| * The {obj}`pyc_collection` attribute for transitively enabling precompiling on | |
| a per-target basis. | |
| * The [Precompiling](precompiling) docs for a guide about using precompiling. | |
| ::: | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.precompile_invalidation_mode"> | |
| <code>precompile_invalidation_mode</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"auto"</code></p> | |
| How precompiled files should be verified to be up-to-date with their associated | |
| source files. Possible values are: | |
| * `auto`: The effective value will be automatically determined by other build | |
| settings. | |
| * `checked_hash`: Use the pyc file if the hash of the source file matches the hash | |
| recorded in the pyc file. This is most useful when working with code that | |
| you may modify. | |
| * `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against | |
| the source file. This is most useful when the code won't be modified. | |
| For more information on pyc invalidation modes, see | |
| https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.precompile_optimize_level"> | |
| <code>precompile_optimize_level</code> | |
| </td> | |
| <td> | |
| <p>Integer; default is <code>0</code></p> | |
| The optimization level for precompiled files. | |
| For more information about optimization levels, see the `compile()` function's | |
| `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile | |
| NOTE: The value `-1` means "current interpreter", which will be the interpreter | |
| used _at build time when pycs are generated_, not the interpreter used at | |
| runtime when the code actually runs. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.precompile_source_retention"> | |
| <code>precompile_source_retention</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"inherit"</code></p> | |
| Determines, when a source file is compiled, if the source file is kept | |
| in the resulting output or not. Valid values are: | |
| * `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. | |
| * `keep_source`: Include the original Python source. | |
| * `omit_source`: Don't include the original py source. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.pyc_collection"> | |
| <code>pyc_collection</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"inherit"</code></p> | |
| Determines whether pyc files from dependencies should be manually included. | |
| Valid values are: | |
| * `inherit`: Inherit the value from {flag}`--precompile`. | |
| * `include_pyc`: Add implicitly generated pyc files from dependencies. i.e. | |
| pyc files for targets that specify {attr}`precompile="inherit"`. | |
| * `disabled`: Don't add implicitly generated pyc files. Note that | |
| pyc files may still come from dependencies that enable precompiling at the | |
| target level. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.python_version"> | |
| <code>python_version</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"PY3"</code></p> | |
| Defunct, unused, does nothing. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.srcs_version"> | |
| <code>srcs_version</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"PY2AND3"</code></p> | |
| Defunct, unused, does nothing. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.stamp"> | |
| <code>stamp</code> | |
| </td> | |
| <td> | |
| <p>Integer; default is <code>-1</code></p> | |
| Whether to encode build information into the binary. Possible values: | |
| * `stamp = 1`: Always stamp the build information into the binary, even in | |
| `--nostamp` builds. **This setting should be avoided**, since it potentially kills | |
| remote caching for the binary and any downstream actions that depend on it. | |
| * `stamp = 0`: Always replace build information by constant values. This gives | |
| good build result caching. | |
| * `stamp = -1`: Embedding of build information is controlled by the | |
| `--[no]stamp` flag. | |
| Stamped binaries are not rebuilt unless their dependencies change. | |
| WARNING: Stamping can harm build performance by reducing cache hits and should | |
| be avoided if possible. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="py_library"> | |
| py_library | |
| </h2> | |
| <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_library_rule.bzl" target="_blank"> | |
| View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> | |
| </a> | |
| <pre class="rule-signature">py_library(<a href="#py_library.name">name</a>, <a href="#py_library.deps">deps</a>, <a href="#py_library.srcs">srcs</a>, <a href="#py_library.data">data</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#py_library.imports">imports</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#py_library.precompile">precompile</a>, <a href="#py_library.precompile_invalidation_mode">precompile_invalidation_mode</a>, <a href="#py_library.precompile_optimize_level">precompile_optimize_level</a>, <a href="#py_library.precompile_source_retention">precompile_source_retention</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#py_library.srcs_version">srcs_version</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> | |
| A library of Python code that can be depended upon. | |
| Default outputs: | |
| * The input Python sources | |
| * The precompiled artifacts from the sources. | |
| NOTE: Precompilation affects which of the default outputs are included in the | |
| resulting runfiles. See the precompile-related attributes and flags for | |
| more information. | |
| :::{versionchanged} 0.37.0 | |
| Source files are no longer added to the runfiles directly. | |
| ::: | |
| <h3 id="py_library_args">Arguments</h3> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th colspan="2">Attributes</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="py_library.name"><code>name</code></td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels#target-names">Name</a>; required</p> | |
| <p>A unique name for this target.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.deps"> | |
| <code>deps</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/8.3.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| List of additional libraries to be linked in to the target. | |
| See comments about | |
| the [`deps` attribute typically defined by | |
| rules](https://bazel.build/reference/be/common-definitions#typical-attributes). | |
| These are typically `py_library` rules. | |
| Targets that only provide data files used at runtime belong in the `data` | |
| attribute. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.srcs"> | |
| <code>srcs</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/8.3.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| The list of Python source files that are processed to create the target. This | |
| includes all your checked-in code and may include generated source files. The | |
| `.py` files belong in `srcs` and library targets belong in `deps`. Other binary | |
| files that may be needed at run time belong in `data`. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.data"> | |
| <code>data</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/8.3.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| The list of files need by this library at runtime. See comments about | |
| the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). | |
| There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. | |
| This is because Python has a concept of runtime resources. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.imports"> | |
| <code>imports</code> | |
| </td> | |
| <td> | |
| <p>List of strings; default is <code>[]</code></p> | |
| List of import directories to be added to the PYTHONPATH. | |
| Subject to "Make variable" substitution. These import directories will be added | |
| for this rule and all rules that depend on it (note: not the rules this rule | |
| depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules | |
| that depend on this rule. The strings are repo-runfiles-root relative, | |
| Absolute paths (paths that start with `/`) and paths that references a path | |
| above the execution root are not allowed and will result in an error. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.precompile"> | |
| <code>precompile</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"inherit"</code></p> | |
| Whether py source files **for this target** should be precompiled. | |
| Values: | |
| * `inherit`: Allow the downstream binary decide if precompiled files are used. | |
| * `enabled`: Compile Python source files at build time. | |
| * `disabled`: Don't compile Python source files at build time. | |
| :::{seealso} | |
| * The {flag}`--precompile` flag, which can override this attribute in some cases | |
| and will affect all targets when building. | |
| * The {obj}`pyc_collection` attribute for transitively enabling precompiling on | |
| a per-target basis. | |
| * The [Precompiling](precompiling) docs for a guide about using precompiling. | |
| ::: | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.precompile_invalidation_mode"> | |
| <code>precompile_invalidation_mode</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"auto"</code></p> | |
| How precompiled files should be verified to be up-to-date with their associated | |
| source files. Possible values are: | |
| * `auto`: The effective value will be automatically determined by other build | |
| settings. | |
| * `checked_hash`: Use the pyc file if the hash of the source file matches the hash | |
| recorded in the pyc file. This is most useful when working with code that | |
| you may modify. | |
| * `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against | |
| the source file. This is most useful when the code won't be modified. | |
| For more information on pyc invalidation modes, see | |
| https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.precompile_optimize_level"> | |
| <code>precompile_optimize_level</code> | |
| </td> | |
| <td> | |
| <p>Integer; default is <code>0</code></p> | |
| The optimization level for precompiled files. | |
| For more information about optimization levels, see the `compile()` function's | |
| `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile | |
| NOTE: The value `-1` means "current interpreter", which will be the interpreter | |
| used _at build time when pycs are generated_, not the interpreter used at | |
| runtime when the code actually runs. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.precompile_source_retention"> | |
| <code>precompile_source_retention</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"inherit"</code></p> | |
| Determines, when a source file is compiled, if the source file is kept | |
| in the resulting output or not. Valid values are: | |
| * `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. | |
| * `keep_source`: Include the original Python source. | |
| * `omit_source`: Don't include the original py source. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.srcs_version"> | |
| <code>srcs_version</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"PY2AND3"</code></p> | |
| Defunct, unused, does nothing. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="py_test"> | |
| py_test | |
| </h2> | |
| <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_test_rule.bzl" target="_blank"> | |
| View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> | |
| </a> | |
| <pre class="rule-signature">py_test(<a href="#py_test.name">name</a>, <a href="#py_test.deps">deps</a>, <a href="#py_test.srcs">srcs</a>, <a href="#py_test.data">data</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#test.flaky">flaky</a>, <a href="#py_test.imports">imports</a>, <a href="#py_test.legacy_create_init">legacy_create_init</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#test.local">local</a>, <a href="#py_test.main">main</a>, <a href="#py_test.precompile">precompile</a>, <a href="#py_test.precompile_invalidation_mode">precompile_invalidation_mode</a>, <a href="#py_test.precompile_optimize_level">precompile_optimize_level</a>, <a href="#py_test.precompile_source_retention">precompile_source_retention</a>, <a href="#py_test.pyc_collection">pyc_collection</a>, <a href="#py_test.python_version">python_version</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="#py_test.srcs_version">srcs_version</a>, <a href="#py_test.stamp">stamp</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> | |
| <h3 id="py_test_args">Arguments</h3> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th colspan="2">Attributes</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="py_test.name"><code>name</code></td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels#target-names">Name</a>; required</p> | |
| <p>A unique name for this target.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.deps"> | |
| <code>deps</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/8.3.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| List of additional libraries to be linked in to the target. | |
| See comments about | |
| the [`deps` attribute typically defined by | |
| rules](https://bazel.build/reference/be/common-definitions#typical-attributes). | |
| These are typically `py_library` rules. | |
| Targets that only provide data files used at runtime belong in the `data` | |
| attribute. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.srcs"> | |
| <code>srcs</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/8.3.0/concepts/labels">labels</a>; required</p> | |
| The list of Python source files that are processed to create the target. This | |
| includes all your checked-in code and may include generated source files. The | |
| `.py` files belong in `srcs` and library targets belong in `deps`. Other binary | |
| files that may be needed at run time belong in `data`. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.data"> | |
| <code>data</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/8.3.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| The list of files need by this library at runtime. See comments about | |
| the [`data` attribute typically defined by rules](https://bazel.build/reference/be/common-definitions#typical-attributes). | |
| There is no `py_embed_data` like there is `cc_embed_data` and `go_embed_data`. | |
| This is because Python has a concept of runtime resources. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.imports"> | |
| <code>imports</code> | |
| </td> | |
| <td> | |
| <p>List of strings; default is <code>[]</code></p> | |
| List of import directories to be added to the PYTHONPATH. | |
| Subject to "Make variable" substitution. These import directories will be added | |
| for this rule and all rules that depend on it (note: not the rules this rule | |
| depends on. Each directory will be added to `PYTHONPATH` by `py_binary` rules | |
| that depend on this rule. The strings are repo-runfiles-root relative, | |
| Absolute paths (paths that start with `/`) and paths that references a path | |
| above the execution root are not allowed and will result in an error. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.legacy_create_init"> | |
| <code>legacy_create_init</code> | |
| </td> | |
| <td> | |
| <p>Integer; default is <code>-1</code></p> | |
| Whether to implicitly create empty `__init__.py` files in the runfiles tree. | |
| These are created in every directory containing Python source code or shared | |
| libraries, and every parent directory of those directories, excluding the repo | |
| root directory. The default, `-1` (auto), means true unless | |
| `--incompatible_default_to_explicit_init_py` is used. If false, the user is | |
| responsible for creating (possibly empty) `__init__.py` files and adding them to | |
| the `srcs` of Python targets as required. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.main"> | |
| <code>main</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels">Label</a>; default is <code>None</code></p> | |
| Optional; the name of the source file that is the main entry point of the | |
| application. This file must also be listed in `srcs`. If left unspecified, | |
| `name`, with `.py` appended, is used instead. If `name` does not match any | |
| filename in `srcs`, `main` must be specified. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.precompile"> | |
| <code>precompile</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"inherit"</code></p> | |
| Whether py source files **for this target** should be precompiled. | |
| Values: | |
| * `inherit`: Allow the downstream binary decide if precompiled files are used. | |
| * `enabled`: Compile Python source files at build time. | |
| * `disabled`: Don't compile Python source files at build time. | |
| :::{seealso} | |
| * The {flag}`--precompile` flag, which can override this attribute in some cases | |
| and will affect all targets when building. | |
| * The {obj}`pyc_collection` attribute for transitively enabling precompiling on | |
| a per-target basis. | |
| * The [Precompiling](precompiling) docs for a guide about using precompiling. | |
| ::: | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.precompile_invalidation_mode"> | |
| <code>precompile_invalidation_mode</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"auto"</code></p> | |
| How precompiled files should be verified to be up-to-date with their associated | |
| source files. Possible values are: | |
| * `auto`: The effective value will be automatically determined by other build | |
| settings. | |
| * `checked_hash`: Use the pyc file if the hash of the source file matches the hash | |
| recorded in the pyc file. This is most useful when working with code that | |
| you may modify. | |
| * `unchecked_hash`: Always use the pyc file; don't check the pyc's hash against | |
| the source file. This is most useful when the code won't be modified. | |
| For more information on pyc invalidation modes, see | |
| https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.precompile_optimize_level"> | |
| <code>precompile_optimize_level</code> | |
| </td> | |
| <td> | |
| <p>Integer; default is <code>0</code></p> | |
| The optimization level for precompiled files. | |
| For more information about optimization levels, see the `compile()` function's | |
| `optimize` arg docs at https://docs.python.org/3/library/functions.html#compile | |
| NOTE: The value `-1` means "current interpreter", which will be the interpreter | |
| used _at build time when pycs are generated_, not the interpreter used at | |
| runtime when the code actually runs. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.precompile_source_retention"> | |
| <code>precompile_source_retention</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"inherit"</code></p> | |
| Determines, when a source file is compiled, if the source file is kept | |
| in the resulting output or not. Valid values are: | |
| * `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag. | |
| * `keep_source`: Include the original Python source. | |
| * `omit_source`: Don't include the original py source. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.pyc_collection"> | |
| <code>pyc_collection</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"inherit"</code></p> | |
| Determines whether pyc files from dependencies should be manually included. | |
| Valid values are: | |
| * `inherit`: Inherit the value from {flag}`--precompile`. | |
| * `include_pyc`: Add implicitly generated pyc files from dependencies. i.e. | |
| pyc files for targets that specify {attr}`precompile="inherit"`. | |
| * `disabled`: Don't add implicitly generated pyc files. Note that | |
| pyc files may still come from dependencies that enable precompiling at the | |
| target level. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.python_version"> | |
| <code>python_version</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"PY3"</code></p> | |
| Defunct, unused, does nothing. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.srcs_version"> | |
| <code>srcs_version</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"PY2AND3"</code></p> | |
| Defunct, unused, does nothing. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.stamp"> | |
| <code>stamp</code> | |
| </td> | |
| <td> | |
| <p>Integer; default is <code>0</code></p> | |
| Whether to encode build information into the binary. Possible values: | |
| * `stamp = 1`: Always stamp the build information into the binary, even in | |
| `--nostamp` builds. **This setting should be avoided**, since it potentially kills | |
| remote caching for the binary and any downstream actions that depend on it. | |
| * `stamp = 0`: Always replace build information by constant values. This gives | |
| good build result caching. | |
| * `stamp = -1`: Embedding of build information is controlled by the | |
| `--[no]stamp` flag. | |
| Stamped binaries are not rebuilt unless their dependencies change. | |
| WARNING: Stamping can harm build performance by reducing cache hits and should | |
| be avoided if possible. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="py_runtime"> | |
| py_runtime | |
| </h2> | |
| <a class="button button-with-icon" href="https://github.com/bazelbuild/rules_python/tree/0.40.0/python/private/py_runtime_rule.bzl" target="_blank"> | |
| View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> | |
| </a> | |
| <pre class="rule-signature">py_runtime(<a href="#py_runtime.name">name</a>, <a href="#py_runtime.abi_flags">abi_flags</a>, <a href="#py_runtime.bootstrap_template">bootstrap_template</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#py_runtime.coverage_tool">coverage_tool</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#py_runtime.files">files</a>, <a href="#py_runtime.implementation_name">implementation_name</a>, <a href="#py_runtime.interpreter">interpreter</a>, <a href="#py_runtime.interpreter_path">interpreter_path</a>, <a href="#py_runtime.interpreter_version_info">interpreter_version_info</a>, <a href="#py_runtime.pyc_tag">pyc_tag</a>, <a href="#py_runtime.python_version">python_version</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#py_runtime.stage2_bootstrap_template">stage2_bootstrap_template</a>, <a href="#py_runtime.stub_shebang">stub_shebang</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#py_runtime.zip_main_template">zip_main_template</a>)</pre> | |
| Represents a Python runtime used to execute Python code. | |
| A `py_runtime` target can represent either a *platform runtime* or an *in-build | |
| runtime*. A platform runtime accesses a system-installed interpreter at a known | |
| path, whereas an in-build runtime points to an executable target that acts as | |
| the interpreter. In both cases, an "interpreter" means any executable binary or | |
| wrapper script that is capable of running a Python script passed on the command | |
| line, following the same conventions as the standard CPython interpreter. | |
| A platform runtime is by its nature non-hermetic. It imposes a requirement on | |
| the target platform to have an interpreter located at a specific path. An | |
| in-build runtime may or may not be hermetic, depending on whether it points to | |
| a checked-in interpreter or a wrapper script that accesses the system | |
| interpreter. | |
| Example | |
| ``` | |
| 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", | |
| ) | |
| ``` | |
| <h3 id="py_runtime_args">Arguments</h3> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th colspan="2">Attributes</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="py_runtime.name"><code>name</code></td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels#target-names">Name</a>; required</p> | |
| <p>A unique name for this target.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.abi_flags"> | |
| <code>abi_flags</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"<AUTO>"</code></p> | |
| The runtime's ABI flags, i.e. `sys.abiflags`. | |
| If not set, then it will be set based on flags. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.bootstrap_template"> | |
| <code>bootstrap_template</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:bootstrap_template"</code></p> | |
| The bootstrap script template file to use. Should have %python_binary%, | |
| %workspace_name%, %main%, and %imports%. | |
| This template, after expansion, becomes the executable file used to start the | |
| process, so it is responsible for initial bootstrapping actions such as finding | |
| the Python interpreter, runfiles, and constructing an environment to run the | |
| intended Python application. | |
| While this attribute is currently optional, it will become required when the | |
| Python rules are moved out of Bazel itself. | |
| The exact variable names expanded is an unstable API and is subject to change. | |
| The API will become more stable when the Python rules are moved out of Bazel | |
| itself. | |
| See @bazel_tools//tools/python:python_bootstrap_template.txt for more variables. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.coverage_tool"> | |
| <code>coverage_tool</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels">Label</a>; default is <code>None</code></p> | |
| This is a target to use for collecting code coverage information from | |
| {rule}`py_binary` and {rule}`py_test` targets. | |
| If set, the target must either produce a single file or be an executable target. | |
| The path to the single file, or the executable if the target is executable, | |
| determines the entry point for the python coverage tool. The target and its | |
| runfiles will be added to the runfiles when coverage is enabled. | |
| The entry point for the tool must be loadable by a Python interpreter (e.g. a | |
| `.py` or `.pyc` file). It must accept the command line arguments | |
| of [`coverage.py`](https://coverage.readthedocs.io), at least including | |
| the `run` and `lcov` subcommands. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.files"> | |
| <code>files</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/8.3.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| For an in-build runtime, this is the set of files comprising this runtime. | |
| These files will be added to the runfiles of Python binaries that use this | |
| runtime. For a platform runtime this attribute must not be set. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.implementation_name"> | |
| <code>implementation_name</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"cpython"</code></p> | |
| The Python implementation name (`sys.implementation.name`) | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.interpreter"> | |
| <code>interpreter</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels">Label</a>; default is <code>None</code></p> | |
| For an in-build runtime, this is the target to invoke as the interpreter. It | |
| can be either of: | |
| * A single file, which will be the interpreter binary. It's assumed such | |
| interpreters are either self-contained single-file executables or any | |
| supporting files are specified in `files`. | |
| * An executable target. The target's executable will be the interpreter binary. | |
| Any other default outputs (`target.files`) and plain files runfiles | |
| (`runfiles.files`) will be automatically included as if specified in the | |
| `files` attribute. | |
| NOTE: the runfiles of the target may not yet be properly respected/propagated | |
| to consumers of the toolchain/interpreter, see | |
| bazelbuild/rules_python/issues/1612 | |
| For a platform runtime (i.e. `interpreter_path` being set) this attribute must | |
| not be set. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.interpreter_path"> | |
| <code>interpreter_path</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>""</code></p> | |
| For a platform runtime, this is the absolute path of a Python interpreter on | |
| the target platform. For an in-build runtime this attribute must not be set. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.interpreter_version_info"> | |
| <code>interpreter_version_info</code> | |
| </td> | |
| <td> | |
| <p>Dictionary: String -> String; default is <code>{}</code></p> | |
| Version information about the interpreter this runtime provides. | |
| If not specified, uses {obj}`--python_version` | |
| The supported keys match the names for `sys.version_info`. While the input | |
| values are strings, most are converted to ints. The supported keys are: | |
| * major: int, the major version number | |
| * minor: int, the minor version number | |
| * micro: optional int, the micro version number | |
| * releaselevel: optional str, the release level | |
| * serial: optional int, the serial number of the release | |
| :::{versionchanged} 0.36.0 | |
| {obj}`--python_version` determines the default value. | |
| ::: | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.pyc_tag"> | |
| <code>pyc_tag</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>""</code></p> | |
| Optional string; the tag portion of a pyc filename, e.g. the `cpython-39` infix | |
| of `foo.cpython-39.pyc`. See PEP 3147. If not specified, it will be computed | |
| from `implementation_name` and `interpreter_version_info`. If no pyc_tag is | |
| available, then only source-less pyc generation will function correctly. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.python_version"> | |
| <code>python_version</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"PY3"</code></p> | |
| Whether this runtime is for Python major version 2 or 3. Valid values are `"PY2"` | |
| and `"PY3"`. | |
| The default value is controlled by the `--incompatible_py3_is_default` flag. | |
| However, in the future this attribute will be mandatory and have no default | |
| value. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.stage2_bootstrap_template"> | |
| <code>stage2_bootstrap_template</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:stage2_bootstrap_template"</code></p> | |
| The template to use when two stage bootstrapping is enabled | |
| :::{seealso} | |
| {obj}`PyRuntimeInfo.stage2_bootstrap_template` and {obj}`--bootstrap_impl` | |
| ::: | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.stub_shebang"> | |
| <code>stub_shebang</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"#!/usr/bin/env python3"</code></p> | |
| "Shebang" expression prepended to the bootstrapping Python stub script | |
| used when executing {rule}`py_binary` targets. | |
| See https://github.com/bazelbuild/bazel/issues/8685 for | |
| motivation. | |
| Does not apply to Windows. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.zip_main_template"> | |
| <code>zip_main_template</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/8.3.0/concepts/labels">Label</a>; default is <code>"@rules_python//python/private:zip_main_template"</code></p> | |
| The template to use for a zip's top-level `__main__.py` file. | |
| This becomes the entry point executed when `python foo.zip` is run. | |
| :::{seealso} | |
| The {obj}`PyRuntimeInfo.zip_main_template` field. | |
| ::: | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <!-- Generated footer --> | |
| </body> | |
| </html> |