feat(toolchain): allow users easily override coverage #3902

This ticket I am going to repurpose for implementing some sort of method to allow users override coverage library used.

Things that we could do:

• Get rid of the py script calling pip -> vendor the bzl file to load from. This is somewhat hard to maintain and when new toolchain version get added (or removed) the file may get stale. Goal state is - We have bzlmod API to set the versions and we have a diff_test to actually do the vendoring of the .bzl file. We should leverage uv.lock files to actually do the configuration, they can be either user or rules_python supplied.
• Make the coverage package more similar to regular pip packages. Currently it is just an http_archive, but in reality we could have potentially something that is more similar to how it is configured. Potentials:
  • Create a coverage_collector rule that would not require us patching the coverage wheel.
  • Change the coverage collector bootstrap to not require patching.
  • Just include the py_library into the venv and let the rest work out naturally.
• Have a some sort of hub for the coverage tool that is created by pip.parse(hub="coverage") where we use_repo("coverage") and then have in @rules_python an alias for the coverage tool. The python.toolchain then has python.default(coverage="@rules_python//python/private:coverage_alias"). The main idea is that this configuration could accept a regular target. Maybe we can depend on extracted_whl_srcs.

Out of scope:

• Make pip.dep somehow provide package version, markers, etc to download a particular package. This is similar to feat(pypi): add pip.dep to declare abstract pypi dependencies #3850, but the idea is:
  • We (for now only rules_python) can define a default fallback venv to the unified_hub_repo alias, so that if the user does not select anything, it just works.
  • We use @pypi//coverage and it just works, if the user has a different coverage package version in their venv, it gets used instead.
  • The logic for such deps may be that this is for particular tools, like twine, pip, pip-tools, coverage. The interesting thing is that those tools could be each in its own venv if we are using them in exec configuration, i.e. as a tool runner. This suggests that we may need to rething this approach of using @pypi//<dep> and instead have something like @pypi//<dep> or @pypi_tool//<dep> where we should have something similar to the Add optional dependencies to the universal_hub #3923. For now we shall allow users define a different version.

TODO

PRs that can be reviewed independently:

• refactor(toolchain): store the bundled coverage wheels as a flat uv.lock-like list (struct(url, hash = "sha256:...", marker = ...)) and select the wheel with select_whl (refactor(toolchain): select bundled coverage wheels with select_whl #4414).
• test(coverage): check the coverage collection with the bundled coverage tool as part of bazel test using py_reconfig_test (test(coverage): check the coverage collection with the bundled coverage tool #4417).
• fix(toolchain): keep the strip_prefix when python.single_version_override does not override the urls; it used to reset the strip_prefix of the full archives (freethreaded builds of e.g. 3.13.0) (fix(toolchain): keep the strip_prefix when single_version_override has no urls #4435).

Stacked PRs (merge in order, each contains the previous ones):

• feat(toolchain): allow the extracted coverage wheel (e.g. @pypi//coverage:extracted_whl_files) as py_runtime.coverage_tool; adds coverage to the dev deps and a py_reconfig_test that collects coverage with it (feat(toolchain): allow using a py_library such as @pypi//coverage as the coverage_tool #4433, on top of test(coverage): check the coverage collection with the bundled coverage tool #4417). @pypi//coverage (the py_library) cannot be used, because it depends on the Python toolchain and creates a dependency cycle.
• feat(toolchain): python.single_version_override(coverage_tool = ...) and python_register_toolchains(coverage_tool = ...) to set the coverage tool for all platforms of a version; the feat(toolchain): allow using a py_library such as @pypi//coverage as the coverage_tool #4433 test toolchain uses it (feat(toolchain): set the coverage_tool for all platforms of a version #4434, on top of feat(toolchain): allow using a py_library such as @pypi//coverage as the coverage_tool #4433).
• feat(toolchain): generate the select_whl platform parameters from the python version and the toolchain platform so that the platform specific wheels are used for more platforms (e.g. musllinux, riscv64, i686) instead of falling back to py3-none-any (feat(toolchain): use a uv.lock based coverage hub for the bzlmod toolchains #4415, on top of refactor(toolchain): select bundled coverage wheels with select_whl #4414).
• build(coverage): define the bundled coverage versions in a pyproject.toml and update the wheels from the uv.lock file (build(coverage): update the bundled coverage wheels from a uv.lock file #4418, on top of feat(toolchain): use a uv.lock based coverage hub for the bzlmod toolchains #4415 and test(coverage): check the coverage collection with the bundled coverage tool #4417).
• feat(coverage): use the latest coverage.py for the latest python versions and keep the old release only for the old python versions (feat(coverage): use the latest coverage.py for the latest python versions #4420, on top of build(coverage): update the bundled coverage wheels from a uv.lock file #4418).

Follow-ups:

• Drop coverage.patch once Bazel 7 is no longer supported: the rules_python bootstrap imports coverage in-process, so the sys.path patch of coverage/__main__.py only matters if the entry point is executed as a script (e.g. by the Bazel 7 native rules). The feat(toolchain): allow using a py_library such as @pypi//coverage as the coverage_tool #4433 test shows that the unpatched PyPI wheel works.
• Decide whether the bundled coverage wheels should be deprecated in favour of the user supplied ones.

Done:

• Warn when bazel coverage is run and the selected runtime has no coverage tool, pointing to the docs (fix(coverage): warn about a missing coverage wheel only for the selected runtime #3955).

Related:

• perf(pypi): extract downloaded wheels once and reuse them #3856 extracts each downloaded wheel once and reuses it across python versions and hubs, so the coverage wheel from a hub is not extracted once per python version.