<html devsite>
<head>
  <meta name="project_path" value="/_project.yaml">
  <meta name="book_path" value="/versions/6.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>



<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>

  <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 = [":testlib"],
)

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><code><a href="/versions/6.5.0/concepts/labels#target-names">Name</a>; required</code></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><code>List of <a href="/versions/6.5.0/concepts/labels">labels</a>; optional</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/6.5.0/reference/be/common-definitions#typical-attributes">
          Typical attributes defined by most build rules</a>.
          These are generally
          <a href="/versions/6.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><code>List of <a href="/versions/6.5.0/concepts/labels">labels</a>; required</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. 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><code>List of strings; optional</code></p>
                              List of import directories to be added to the <code>PYTHONPATH</code>.
          <p>
          Subject to <a href="/versions/6.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/6.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><code>Integer; optional; default is -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><code><a href="/versions/6.5.0/concepts/labels">Label</a>; optional</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><code>String; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is "_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><code>String; optional; default is "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/6.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 &lt;your target&gt; \
              --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><code>Integer; optional; default is -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/6.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/6.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>

  <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><code><a href="/versions/6.5.0/concepts/labels#target-names">Name</a>; required</code></p>
          <p>A unique name for this target.</p>

        </td>
      </tr>
                <tr>
        <td id="py_library.deps">
          <code>deps</code>
        </td>
        <td>
                    <p><code>List of <a href="/versions/6.5.0/concepts/labels">labels</a>; optional</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/6.5.0/reference/be/common-definitions#typical-attributes">
          Typical attributes defined by most build rules</a>.
          These are generally
          <a href="/versions/6.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><code>List of <a href="/versions/6.5.0/concepts/labels">labels</a>; optional</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><code>List of strings; optional</code></p>
                              List of import directories to be added to the <code>PYTHONPATH</code>.
          <p>
          Subject to <a href="/versions/6.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/6.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><code>String; optional; default is "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/6.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 &lt;your target&gt; \
              --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>

  <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><code><a href="/versions/6.5.0/concepts/labels#target-names">Name</a>; required</code></p>
          <p>A unique name for this target.</p>

        </td>
      </tr>
                <tr>
        <td id="py_test.deps">
          <code>deps</code>
        </td>
        <td>
                    <p><code>List of <a href="/versions/6.5.0/concepts/labels">labels</a>; optional</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/6.5.0/reference/be/common-definitions#typical-attributes">
          Typical attributes defined by most build rules</a>.
          These are generally
          <a href="/versions/6.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><code>List of <a href="/versions/6.5.0/concepts/labels">labels</a>; required</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. 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><code>List of strings; optional</code></p>
                              List of import directories to be added to the <code>PYTHONPATH</code>.
          <p>
          Subject to <a href="/versions/6.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/6.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><code>Integer; optional; default is -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><code><a href="/versions/6.5.0/concepts/labels">Label</a>; optional</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><code>String; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is "_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><code>String; optional; default is "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/6.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 &lt;your target&gt; \
              --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><code>Integer; optional; default is 0</code></p>
                            See the section on <a href="/versions/6.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>

  <pre class="rule-signature">py_runtime(<a href="#py_runtime.name">name</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><code><a href="/versions/6.5.0/concepts/labels#target-names">Name</a>; required</code></p>
          <p>A unique name for this target.</p>

        </td>
      </tr>
                          <tr>
        <td id="py_runtime.coverage_tool">
          <code>coverage_tool</code>
        </td>
        <td>
                    <p><code><a href="/versions/6.5.0/concepts/labels">Label</a>; optional</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><code>List of <a href="/versions/6.5.0/concepts/labels">labels</a>; optional</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><code><a href="/versions/6.5.0/concepts/labels">Label</a>; optional</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><code>String; optional</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><code>String; optional; default is "_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><code>String; optional; default is "#!/usr/bin/env python3"</code></p>
                            "Shebang" expression prepended to the bootstrapping Python stub 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>
