rules/python: Add a coverage_tool attribute to py_runtime.

site/en/configure/coverage.md

@@ -188,8 +188,61 @@ py_test(
     ],
 )
 ```
-<!-- TODO: Allow specifying a target for `PYTHON_COVERAGE`, instead of having to use `$(location)` -->
 
+If you are using a hermetic Python toolchain, instead of adding the coverage
+dependency to every `py_test` target you can instead add the coverage tool to
+the toolchain configuration.
+
+Because the [pip_install][pip_install_rule] rule depends on the Python
+toolchain, it cannot be used to fetch the `coverage` module.
+Instead, add in your `WORKSPACE` e.g.
+
+```starlark
+http_archive(
+    name = "coverage_linux_x86_64"",
+    build_file_content = """
+py_library(
+    name = "coverage",
+    srcs = ["coverage/__main__.py"],
+    data = glob(["coverage/*", "coverage/**/*.py"]),
+    visibility = ["//visibility:public"],
+)
+""",
+    sha256 = "84631e81dd053e8a0d4967cedab6db94345f1c36107c71698f746cb2636c63e3",
+    type = "zip",
+    urls = [
+        "https://files.pythonhosted.org/packages/74/0d/0f3c522312fd27c32e1abe2fb5c323b583a5c108daf2c26d6e8dfdd5a105/coverage-6.4.1-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
+    ],
+)
+```
+
+Then configure your python toolchain as e.g.
+
+```starlark
+py_runtime(
+    name = "py3_runtime_linux_x86_64",
+    coverage_tool = "@coverage_linux_x86_64//:coverage",
+    files = ["@python3_9_x86_64-unknown-linux-gnu//:files"],
+    interpreter = "@python3_9_x86_64-unknown-linux-gnu//:bin/python3",
+    python_version = "PY3",
+)
+
+py_runtime_pair(
+    name = "python_runtimes_linux_x86_64",
+    py2_runtime = None,
+    py3_runtime = ":py3_runtime_linux_x86_64",
+)
+
+toolchain(
+    name = "python_toolchain_linux_x86_64",
+    exec_compatible_with = [
+        "@platforms//os:linux",
+        "@platforms//cpu:x86_64",
+    ],
+    toolchain = ":python_runtimes_linux_x86_64",
+    toolchain_type = "@bazel_tools//tools/python:toolchain_type",
+)
+```
 
 [lcov]: https://github.com/linux-test-project/lcov
 [rules_python]: https://github.com/bazelbuild/rules_python

src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonSemantics.java

@@ -92,12 +92,20 @@ public boolean prohibitHyphensInPackagePaths() {
   public void collectRunfilesForBinary(
       RuleContext ruleContext, Runfiles.Builder builder, PyCommon common, CcInfo ccInfo) {
     addRuntime(ruleContext, common, builder);
+    // select() and build configuration should ideally remove coverage as
+    // as dependency, but guard against including it at runtime just in case.
+    if (ruleContext.getConfiguration().isCodeCoverageEnabled()) {
+      addCoverageSupport(ruleContext, common, builder);
+    }
   }
 
   @Override
   public void collectDefaultRunfilesForBinary(
       RuleContext ruleContext, PyCommon common, Runfiles.Builder builder) {
     addRuntime(ruleContext, common, builder);
+    if (ruleContext.getConfiguration().isCodeCoverageEnabled()) {
+      addCoverageSupport(ruleContext, common, builder);
+    }
   }
 
   @Override
@@ -154,6 +162,9 @@ private static void createStubFile(
     // first-stage.
     String pythonBinary = getPythonBinary(ruleContext, common, bazelConfig);
 
+    // The python code coverage tool to use, if any.
+    String coverageTool = getCoverageTool(ruleContext, common, bazelConfig);
+
     // Version information for host config diagnostic warning.
     PythonVersion attrVersion = PyCommon.readPythonVersionFromAttribute(ruleContext.attributes());
     boolean attrVersionSpecifiedExplicitly = attrVersion != null;
@@ -172,6 +183,7 @@ private static void createStubFile(
                 Substitution.of(
                     "%main%", common.determineMainExecutableSource(/*withWorkspaceName=*/ true)),
                 Substitution.of("%python_binary%", pythonBinary),
+                Substitution.of("%coverage_tool%", coverageTool == null ? "" : coverageTool),
                 Substitution.of("%imports%", Joiner.on(":").join(common.getImports().toList())),
                 Substitution.of("%workspace_name%", ruleContext.getWorkspaceName()),
                 Substitution.of("%is_zipfile%", boolToLiteral(isForZipFile)),
@@ -461,6 +473,32 @@ private static String getPythonBinary(
     return pythonBinary;
   }
 
+  private static void addCoverageSupport(
+      RuleContext ruleContext, PyCommon common, Runfiles.Builder builder) {
+    PyRuntimeInfo provider = getRuntime(ruleContext, common);
+    if (provider != null && provider.getCoverageTool() != null) {
+      builder.addArtifact(provider.getCoverageTool());
+      builder.addTransitiveArtifacts(provider.getCoverageToolFiles());
+    }
+  }
+
+  @Nullable
+  private static String getCoverageTool(
+      RuleContext ruleContext, PyCommon common, BazelPythonConfiguration bazelConfig) {
+    if (!ruleContext.getConfiguration().isCodeCoverageEnabled()) {
+      return null;
+    }
+    String coverageTool = null;
+    PyRuntimeInfo provider = getRuntime(ruleContext, common);
+    if (provider != null && provider.getCoverageTool() != null) {
+      PathFragment workspaceName =
+          PathFragment.create(ruleContext.getRule().getPackage().getWorkspaceName());
+      coverageTool =
+          workspaceName.getRelative(provider.getCoverageTool().getRunfilesPath()).getPathString();
+    }
+    return coverageTool;
+  }
+
   private static String getStubShebang(RuleContext ruleContext, PyCommon common) {
     PyRuntimeInfo provider = getRuntime(ruleContext, common);
     if (provider != null) {