| <html devsite> | |
| <head> | |
| <meta name="project_path" value="/_project.yaml"> | |
| <meta name="book_path" value="/versions/7.5.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 "7.5.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/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPyBinaryRule.java" 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="common-definitions.html#typical.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.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> | |
| <p> | |
| A <code>py_binary</code> is an executable Python program consisting | |
| of a collection of <code>.py</code> source files (possibly belonging | |
| to other <code>py_library</code> rules), a <code>*.runfiles</code> | |
| directory tree containing all the code and data needed by the | |
| program at run-time, and a stub script that starts up the program with | |
| the correct initial environment and data. | |
| </p> | |
| <h4 id="py_binary_examples">Examples</h4> | |
| <pre class="code"> | |
| py_binary( | |
| name = "foo", | |
| srcs = ["foo.py"], | |
| data = [":transform"], # a cc_binary which we invoke at run time | |
| deps = [ | |
| ":foolib", # a py_library | |
| ], | |
| ) | |
| </pre> | |
| <p>If you want to run a <code>py_binary</code> from within another binary or | |
| test (for example, running a python binary to set up some mock resource from | |
| within a java_test) then the correct approach is to make the other binary or | |
| test depend on the <code>py_binary</code> in its data section. The other | |
| binary can then locate the <code>py_binary</code> relative to the source | |
| directory. | |
| </p> | |
| <pre class="code"> | |
| py_binary( | |
| name = "test_main", | |
| srcs = ["test_main.py"], | |
| deps = [":testing"], | |
| ) | |
| java_library( | |
| name = "testing", | |
| srcs = glob(["*.java"]), | |
| data = [":test_main"] | |
| ) | |
| </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/7.5.0/concepts/labels#target-names">Name</a>; required</p> | |
| <p>A unique name for this target.</p> | |
| <br/>If <code>main</code> is unspecified, this should be the same as the name | |
| of the source file that is the main entry point of the application, | |
| minus the extension. For example, if your entry point is called | |
| <code>main.py</code>, then your name should be <code>main</code>. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.deps"> | |
| <code>deps</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/7.5.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| The list of other libraries to be linked in to the binary target. | |
| See general comments about <code>deps</code> at | |
| <a href="/versions/7.5.0/reference/be/common-definitions#typical-attributes"> | |
| Typical attributes defined by most build rules</a>. | |
| These are generally | |
| <a href="/versions/7.5.0/reference/be/python.html#py_library"><code>py_library</code></a> rules. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.srcs"> | |
| <code>srcs</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/7.5.0/concepts/labels">labels</a>; required</p> | |
| The list of source (<code>.py</code>) files that are processed to create the target. | |
| This includes all your checked-in code and any generated source files. Library targets | |
| belong in <code>deps</code> instead, while other binary files needed at runtime belong in | |
| <code>data</code>. | |
| </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 <code>PYTHONPATH</code>. | |
| <p> | |
| Subject to <a href="/versions/7.5.0/reference/be/make-variables">"Make variable"</a> 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 <code>PYTHONPATH</code> by | |
| <a href="/versions/7.5.0/reference/be/python.html#py_binary"><code>py_binary</code></a> rules that depend on this rule. | |
| </p> | |
| <p> | |
| Absolute paths (paths that start with <code>/</code>) and paths that references a path | |
| above the execution root are not allowed and will result in an error. | |
| </p> | |
| </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, auto, means true unless | |
| <code>--incompatible_default_to_explicit_init_py</code> is used. If false, the user is | |
| responsible for creating (possibly empty) __init__.py files and adding them to the | |
| <code>srcs</code> of Python targets as required. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.main"> | |
| <code>main</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/7.5.0/concepts/labels">Label</a>; default is <code>None</code></p> | |
| The name of the source file that is the main entry point of the application. | |
| This file must also be listed in <code>srcs</code>. If left unspecified, | |
| <code>name</code> is used instead (see above). If <code>name</code> does not | |
| match any filename in <code>srcs</code>, <code>main</code> must be specified. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.python_version"> | |
| <code>python_version</code> | |
| </td> | |
| <td> | |
| <p>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>"_INTERNAL_SENTINEL"</code></p> | |
| Whether to build this target (and its transitive <code>deps</code>) for Python 2 or Python | |
| 3. Valid values are <code>"PY2"</code> and <code>"PY3"</code> (the default). | |
| <p>The Python version is always reset (possibly by default) to whatever version is | |
| specified by this attribute, regardless of the version specified on the command line or by | |
| other higher targets that depend on this one. | |
| <p>If you want to <code>select()</code> on the current Python version, you can inspect the | |
| value of <code>@rules_python//python:python_version</code>. See | |
| <a href="https://github.com/bazelbuild/rules_python/blob/120590e2f2b66e5590bf4dc8ebef9c5338984775/python/BUILD#L43">here</a> | |
| for more information. | |
| <p><b>Bug warning:</b> This attribute sets the version for which Bazel builds your target, | |
| but due to <a href="https://github.com/bazelbuild/bazel/issues/4815">#4815</a>, the | |
| resulting stub script may still invoke the wrong interpreter version at runtime. See | |
| <a href="https://github.com/bazelbuild/bazel/issues/4815#issuecomment-460777113">this | |
| workaround</a>, which involves defining a <code>py_runtime</code> target that points to | |
| either Python version as needed, and activating this <code>py_runtime</code> by setting | |
| <code>--python_top</code>. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_binary.srcs_version"> | |
| <code>srcs_version</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"PY2AND3"</code></p> | |
| This attribute declares the target's <code>srcs</code> to be compatible with either Python | |
| 2, Python 3, or both. To actually set the Python runtime version, use the | |
| <a href="/versions/7.5.0/reference/be/python.html#py_binary.python_version"><code>python_version</code></a> attribute of an | |
| executable Python rule (<code>py_binary</code> or <code>py_test</code>). | |
| <p>Allowed values are: <code>"PY2AND3"</code>, <code>"PY2"</code>, and <code>"PY3"</code>. | |
| The values <code>"PY2ONLY"</code> and <code>"PY3ONLY"</code> are also allowed for historic | |
| reasons, but they are essentially the same as <code>"PY2"</code> and <code>"PY3"</code> | |
| and should be avoided. | |
| <p>Note that only the executable rules (<code>py_binary</code> and <code>py_library | |
| </code>) actually verify the current Python version against the value of this attribute. | |
| (This is a feature; since <code>py_library</code> does not change the current Python | |
| version, if it did the validation, it'd be impossible to build both <code>PY2ONLY</code> | |
| and <code>PY3ONLY</code> libraries in the same invocation.) Furthermore, if there is a | |
| version mismatch, the error is only reported in the execution phase. In particular, the | |
| error will not appear in a <code>bazel build --nobuild</code> invocation.) | |
| <p>To get diagnostic information about which dependencies introduce version requirements, | |
| you can run the <code>find_requirements</code> aspect on your target: | |
| <pre> | |
| bazel build <your target> \ | |
| --aspects=@rules_python//python:defs.bzl%find_requirements \ | |
| --output_groups=pyversioninfo | |
| </pre> | |
| This will build a file with the suffix <code>-pyversioninfo.txt</code> giving information | |
| about why your target requires one Python version or another. Note that it works even if | |
| the given target failed to build due to a version conflict. | |
| </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: | |
| <ul> | |
| <li> | |
| <code>stamp = 1</code>: Always stamp the build information into the binary, even in | |
| <a href="/versions/7.5.0/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <b>This | |
| setting should be avoided</b>, since it potentially kills remote caching for the | |
| binary and any downstream actions that depend on it. | |
| </li> | |
| <li> | |
| <code>stamp = 0</code>: Always replace build information by constant values. This | |
| gives good build result caching. | |
| </li> | |
| <li> | |
| <code>stamp = -1</code>: Embedding of build information is controlled by the | |
| <a href="/versions/7.5.0/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag. | |
| </li> | |
| </ul> | |
| <p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p> | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="py_library"> | |
| py_library | |
| </h2> | |
| <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPyLibraryRule.java" 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="common-definitions.html#typical.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="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.visibility">visibility</a>)</pre> | |
| <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/7.5.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/7.5.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| The list of other libraries to be linked in to the binary target. | |
| See general comments about <code>deps</code> at | |
| <a href="/versions/7.5.0/reference/be/common-definitions#typical-attributes"> | |
| Typical attributes defined by most build rules</a>. | |
| These are generally | |
| <a href="/versions/7.5.0/reference/be/python.html#py_library"><code>py_library</code></a> rules. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.srcs"> | |
| <code>srcs</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/7.5.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| The list of source (<code>.py</code>) files that are processed to create the target. | |
| This includes all your checked-in code and any generated source files. | |
| </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 <code>PYTHONPATH</code>. | |
| <p> | |
| Subject to <a href="/versions/7.5.0/reference/be/make-variables">"Make variable"</a> 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 <code>PYTHONPATH</code> by | |
| <a href="/versions/7.5.0/reference/be/python.html#py_binary"><code>py_binary</code></a> rules that depend on this rule. | |
| </p> | |
| <p> | |
| Absolute paths (paths that start with <code>/</code>) and paths that references a path | |
| above the execution root are not allowed and will result in an error. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_library.srcs_version"> | |
| <code>srcs_version</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"PY2AND3"</code></p> | |
| This attribute declares the target's <code>srcs</code> to be compatible with either Python | |
| 2, Python 3, or both. To actually set the Python runtime version, use the | |
| <a href="/versions/7.5.0/reference/be/python.html#py_binary.python_version"><code>python_version</code></a> attribute of an | |
| executable Python rule (<code>py_binary</code> or <code>py_test</code>). | |
| <p>Allowed values are: <code>"PY2AND3"</code>, <code>"PY2"</code>, and <code>"PY3"</code>. | |
| The values <code>"PY2ONLY"</code> and <code>"PY3ONLY"</code> are also allowed for historic | |
| reasons, but they are essentially the same as <code>"PY2"</code> and <code>"PY3"</code> | |
| and should be avoided. | |
| <p>Note that only the executable rules (<code>py_binary</code> and <code>py_library | |
| </code>) actually verify the current Python version against the value of this attribute. | |
| (This is a feature; since <code>py_library</code> does not change the current Python | |
| version, if it did the validation, it'd be impossible to build both <code>PY2ONLY</code> | |
| and <code>PY3ONLY</code> libraries in the same invocation.) Furthermore, if there is a | |
| version mismatch, the error is only reported in the execution phase. In particular, the | |
| error will not appear in a <code>bazel build --nobuild</code> invocation.) | |
| <p>To get diagnostic information about which dependencies introduce version requirements, | |
| you can run the <code>find_requirements</code> aspect on your target: | |
| <pre> | |
| bazel build <your target> \ | |
| --aspects=@rules_python//python:defs.bzl%find_requirements \ | |
| --output_groups=pyversioninfo | |
| </pre> | |
| This will build a file with the suffix <code>-pyversioninfo.txt</code> giving information | |
| about why your target requires one Python version or another. Note that it works even if | |
| the given target failed to build due to a version conflict. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="py_test"> | |
| py_test | |
| </h2> | |
| <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPyTestRule.java" 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="common-definitions.html#typical.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.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> | |
| <p> | |
| A <code>py_test()</code> rule compiles a test. A test is a binary wrapper | |
| around some test code.</p> | |
| <h4 id="py_test_examples">Examples</h4> | |
| <p> | |
| <pre class="code"> | |
| py_test( | |
| name = "runtest_test", | |
| srcs = ["runtest_test.py"], | |
| deps = [ | |
| "//path/to/a/py/library", | |
| ], | |
| ) | |
| </pre> | |
| <p>It's also possible to specify a main module:</p> | |
| <pre class="code"> | |
| py_test( | |
| name = "runtest_test", | |
| srcs = [ | |
| "runtest_main.py", | |
| "runtest_lib.py", | |
| ], | |
| main = "runtest_main.py", | |
| ) | |
| </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/7.5.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/7.5.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| The list of other libraries to be linked in to the binary target. | |
| See general comments about <code>deps</code> at | |
| <a href="/versions/7.5.0/reference/be/common-definitions#typical-attributes"> | |
| Typical attributes defined by most build rules</a>. | |
| These are generally | |
| <a href="/versions/7.5.0/reference/be/python.html#py_library"><code>py_library</code></a> rules. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.srcs"> | |
| <code>srcs</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/7.5.0/concepts/labels">labels</a>; required</p> | |
| The list of source (<code>.py</code>) files that are processed to create the target. | |
| This includes all your checked-in code and any generated source files. Library targets | |
| belong in <code>deps</code> instead, while other binary files needed at runtime belong in | |
| <code>data</code>. | |
| </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 <code>PYTHONPATH</code>. | |
| <p> | |
| Subject to <a href="/versions/7.5.0/reference/be/make-variables">"Make variable"</a> 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 <code>PYTHONPATH</code> by | |
| <a href="/versions/7.5.0/reference/be/python.html#py_binary"><code>py_binary</code></a> rules that depend on this rule. | |
| </p> | |
| <p> | |
| Absolute paths (paths that start with <code>/</code>) and paths that references a path | |
| above the execution root are not allowed and will result in an error. | |
| </p> | |
| </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, auto, means true unless | |
| <code>--incompatible_default_to_explicit_init_py</code> is used. If false, the user is | |
| responsible for creating (possibly empty) __init__.py files and adding them to the | |
| <code>srcs</code> of Python targets as required. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.main"> | |
| <code>main</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/7.5.0/concepts/labels">Label</a>; default is <code>None</code></p> | |
| The name of the source file that is the main entry point of the application. | |
| This file must also be listed in <code>srcs</code>. If left unspecified, | |
| <code>name</code> is used instead (see above). If <code>name</code> does not | |
| match any filename in <code>srcs</code>, <code>main</code> must be specified. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.python_version"> | |
| <code>python_version</code> | |
| </td> | |
| <td> | |
| <p>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>"_INTERNAL_SENTINEL"</code></p> | |
| Whether to build this target (and its transitive <code>deps</code>) for Python 2 or Python | |
| 3. Valid values are <code>"PY2"</code> and <code>"PY3"</code> (the default). | |
| <p>The Python version is always reset (possibly by default) to whatever version is | |
| specified by this attribute, regardless of the version specified on the command line or by | |
| other higher targets that depend on this one. | |
| <p>If you want to <code>select()</code> on the current Python version, you can inspect the | |
| value of <code>@rules_python//python:python_version</code>. See | |
| <a href="https://github.com/bazelbuild/rules_python/blob/120590e2f2b66e5590bf4dc8ebef9c5338984775/python/BUILD#L43">here</a> | |
| for more information. | |
| <p><b>Bug warning:</b> This attribute sets the version for which Bazel builds your target, | |
| but due to <a href="https://github.com/bazelbuild/bazel/issues/4815">#4815</a>, the | |
| resulting stub script may still invoke the wrong interpreter version at runtime. See | |
| <a href="https://github.com/bazelbuild/bazel/issues/4815#issuecomment-460777113">this | |
| workaround</a>, which involves defining a <code>py_runtime</code> target that points to | |
| either Python version as needed, and activating this <code>py_runtime</code> by setting | |
| <code>--python_top</code>. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.srcs_version"> | |
| <code>srcs_version</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"PY2AND3"</code></p> | |
| This attribute declares the target's <code>srcs</code> to be compatible with either Python | |
| 2, Python 3, or both. To actually set the Python runtime version, use the | |
| <a href="/versions/7.5.0/reference/be/python.html#py_binary.python_version"><code>python_version</code></a> attribute of an | |
| executable Python rule (<code>py_binary</code> or <code>py_test</code>). | |
| <p>Allowed values are: <code>"PY2AND3"</code>, <code>"PY2"</code>, and <code>"PY3"</code>. | |
| The values <code>"PY2ONLY"</code> and <code>"PY3ONLY"</code> are also allowed for historic | |
| reasons, but they are essentially the same as <code>"PY2"</code> and <code>"PY3"</code> | |
| and should be avoided. | |
| <p>Note that only the executable rules (<code>py_binary</code> and <code>py_library | |
| </code>) actually verify the current Python version against the value of this attribute. | |
| (This is a feature; since <code>py_library</code> does not change the current Python | |
| version, if it did the validation, it'd be impossible to build both <code>PY2ONLY</code> | |
| and <code>PY3ONLY</code> libraries in the same invocation.) Furthermore, if there is a | |
| version mismatch, the error is only reported in the execution phase. In particular, the | |
| error will not appear in a <code>bazel build --nobuild</code> invocation.) | |
| <p>To get diagnostic information about which dependencies introduce version requirements, | |
| you can run the <code>find_requirements</code> aspect on your target: | |
| <pre> | |
| bazel build <your target> \ | |
| --aspects=@rules_python//python:defs.bzl%find_requirements \ | |
| --output_groups=pyversioninfo | |
| </pre> | |
| This will build a file with the suffix <code>-pyversioninfo.txt</code> giving information | |
| about why your target requires one Python version or another. Note that it works even if | |
| the given target failed to build due to a version conflict. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_test.stamp"> | |
| <code>stamp</code> | |
| </td> | |
| <td> | |
| <p>Integer; default is <code>0</code></p> | |
| See the section on <a href="/versions/7.5.0/reference/be/python.html#py_binary_args">py_binary()</a> arguments, except | |
| that the stamp argument is set to 0 by default for tests. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="py_runtime"> | |
| py_runtime | |
| </h2> | |
| <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/python/PyRuntimeRule.java" 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.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.features">features</a>, <a href="#py_runtime.files">files</a>, <a href="#py_runtime.interpreter">interpreter</a>, <a href="#py_runtime.interpreter_path">interpreter_path</a>, <a href="common-definitions.html#typical.licenses">licenses</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.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.visibility">visibility</a>)</pre> | |
| <p>Represents a Python runtime used to execute Python code. | |
| <p>A <code>py_runtime</code> target can represent either a <em>platform runtime</em> or an | |
| <em>in-build runtime</em>. 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. | |
| <p>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. | |
| <h4 id="py_runtime_example">Example:</h4> | |
| <pre class="code"> | |
| 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", | |
| ) | |
| </pre> | |
| <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/7.5.0/concepts/labels#target-names">Name</a>; required</p> | |
| <p>A unique name for this target.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.bootstrap_template"> | |
| <code>bootstrap_template</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/7.5.0/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/python:python_bootstrap_template.txt"</code></p> | |
| Previously referred to as the "Python stub script", this is the | |
| entrypoint to every Python executable target. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.coverage_tool"> | |
| <code>coverage_tool</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/7.5.0/concepts/labels">Label</a>; default is <code>None</code></p> | |
| This is a target to use for collecting code coverage information from <code>py_binary</code> | |
| and <code>py_test</code> targets. | |
| <p>If set, the target must either produce a single file or be and 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.</p> | |
| <p>The entry point for the tool must be loadable by a python interpreter (e.g. a | |
| <code>.py</code> or <code>.pyc</code> file). It must accept the command line arguments | |
| of <a href="https://coverage.readthedocs.io/">coverage.py</a>, at least including | |
| the <code>run</code> and <code>lcov</code> subcommands. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="py_runtime.files"> | |
| <code>files</code> | |
| </td> | |
| <td> | |
| <p>List of <a href="/versions/7.5.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.interpreter"> | |
| <code>interpreter</code> | |
| </td> | |
| <td> | |
| <p><a href="/versions/7.5.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. For a platform | |
| runtime 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.python_version"> | |
| <code>python_version</code> | |
| </td> | |
| <td> | |
| <p>String; default is <code>"_INTERNAL_SENTINEL"</code></p> | |
| Whether this runtime is for Python major version 2 or 3. Valid values are <code>"PY2"</code> | |
| and <code>"PY3"</code>. | |
| <p>The default value is controlled by the <code>--incompatible_py3_is_default</code> flag. | |
| However, in the future this attribute will be mandatory and have no default value. | |
| </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 script | |
| used when executing <code>py_binary</code> targets. | |
| <p>See <a href="https://github.com/bazelbuild/bazel/issues/8685">issue 8685</a> for | |
| motivation. | |
| <p>Does not apply to Windows. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <!-- Generated footer --> | |
| </body> | |
| </html> |