Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
1909697
test(coverage): check the coverage collection with the bundled covera…
aignas Nov 7, 2026
e0351f6
fix: register the coverage dev toolchain with a full python version
aignas Nov 7, 2026
088bce4
test(coverage): check the covered and not covered lines in separate t…
aignas Nov 7, 2026
62be724
feat(toolchain): allow using a py_library as the coverage_tool
aignas Nov 8, 2026
18e6ef7
fix: use the extracted wheel files instead of a py_library
aignas Nov 8, 2026
6b8bbf1
Merge remote-tracking branch 'origin/aignas.test.coverage-collection'…
aignas Nov 8, 2026
08d2743
build(dev): add coverage to the dev dependencies
aignas Nov 8, 2026
0e78f1d
test(coverage): check the coverage collection with coverage from a pi…
aignas Nov 8, 2026
2f48dcb
test(coverage): simplify the coverage collection test setup
aignas Nov 8, 2026
3304042
test(coverage): make collect_code_coverage a bool py_reconfig attr
aignas Nov 8, 2026
4c7e034
Merge remote-tracking branch 'origin/aignas.test.coverage-collection'…
aignas Nov 8, 2026
924c4a8
test(coverage): use the bool collect_code_coverage for instrumented_pypi
aignas Nov 8, 2026
e388a75
docs: link the coverage_tool doc to the coverage docs
aignas Nov 8, 2026
35e08ea
test(coverage): use pytest_test for the coverage collection test
aignas Nov 8, 2026
cb1632f
Merge branch 'aignas.test.coverage-collection' into aignas.feat.cover…
aignas Nov 8, 2026
c9b66df
test(coverage): use pytest_test for the coverage from PyPI test
aignas Nov 8, 2026
a7894e2
Merge branch 'main' into aignas.feat.coverage-tool-py-library
aignas Nov 9, 2026
79d9d12
Merge branch 'main' into aignas.feat.coverage-tool-py-library
aignas Nov 9, 2026
197fcce
fix(toolchain): build the coverage_tool without the toolchain coverag…
aignas Nov 9, 2026
6f653a3
feat(toolchain): import the coverage package using the PyInfo imports
aignas Nov 9, 2026
9451477
Merge remote-tracking branch 'upstream/main' into review_pr_four_four…
rickeylev Nov 14, 2026
de496fe
chore(toolchain): address minor review comments on coverage_tool
rickeylev Nov 14, 2026
6d4f1b3
refactor(toolchain): rename the bootstrap_coverage_tool flag to boots…
aignas Nov 15, 2026
0f941c0
refactor(toolchain): forward the coverage_tool target as PyRuntimeInf…
aignas Nov 15, 2026
1542234
Merge branch 'main' into aignas.feat.coverage-tool-py-library
aignas Nov 15, 2026
8b8a2e5
feat(rules): add PyInfo.packages with the PyPI packages of a target
aignas Nov 15, 2026
5a58165
Merge branch 'feat.aignas.py-info-packages' into aignas.feat.coverage…
aignas Nov 15, 2026
7fa2fde
refactor(coverage): select the coverage package via a flag instead of…
aignas Nov 15, 2026
87190b8
feat(coverage): merge the .coveragerc files of the coverage flag target
aignas Nov 15, 2026
47b1887
docs(coverage): set the bzl default domain so that the cross-referenc…
aignas Nov 15, 2026
3200d0d
fix(rules): resolve the label values in config_settings relative to t…
aignas Nov 15, 2026
06642ce
Revert "fix(rules): resolve the label values in config_settings relat…
aignas Nov 15, 2026
c30a7c5
refactor(coverage): don't detect a coverage dependency via PyInfo.pac…
aignas Nov 15, 2026
de05691
revert: drop PyInfo.packages from this change
aignas Nov 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions dev/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ dependencies = [
"sphinx_rtd_theme >=2.0", # uv insists on downgrading for some reason
"readthedocs-sphinx-ext",
"absl-py",
# Used to test the coverage collection with coverage from a PyPI hub.
"coverage",
"typing-extensions",
"sphinx-reredirects",
"pefile",
Expand Down
264 changes: 264 additions & 0 deletions dev/uv.lock

Large diffs are not rendered by default.

22 changes: 22 additions & 0 deletions docs/api/rules_python/python/config_settings/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,28 @@ This flag replaces the Bazel builtin `--build_python_zip` flag.
:::
::::

::::{bzl:flag} coverage
A target that provides the `coverage` package used by `bazel coverage`, e.g.
`@pypi//coverage`.

This flag is roughly equivalent to putting a target in `deps` when coverage is
collected. It allows using the version of `coverage` locked in the requirements,
together with plugins and a `.coveragerc`, without having to modify the deps of
the executables (`py_binary`, `py_test`) or the Python toolchains.

* Must provide {obj}`PyInfo`.
* It is only added when coverage is collected, and only for the target config,
i.e. build tools don't have it added. It isn't fetched for regular builds.
* The `.coveragerc` files in its runfiles, e.g. from the `data` of a
`py_library`, are merged. See {ref}`coverage-from-pypi`.
* It can be set for a single target with the `config_settings` attribute.

If this flag isn't set, then the `coverage_tool` of the Python runtime is used.

:::{versionadded} VERSION_NEXT_FEATURE
:::
::::

::::{bzl:flag} debugger
A target for providing a custom debugger dependency.

Expand Down
74 changes: 72 additions & 2 deletions docs/coverage.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
:::{default-domain} bzl
:::

# Setting up coverage

As of Bazel 6, the Python toolchains and bootstrap logic supports providing
Expand Down Expand Up @@ -33,8 +36,9 @@ This will implicitly add the version of `coverage` bundled with
`rules_python` to the dependencies of `py_test` rules when `bazel coverage` is
run. If a target already transitively depends on a different version of
`coverage`, then the behavior is undefined -- it is undefined which version comes
first in the import path. If you find yourself in this situation, then you'll
need to manually configure coverage (see below).
first in the import path. If you find yourself in this situation, then set the
{flag}`--coverage` flag to the same `coverage` (see
{ref}`coverage-from-pypi`).
:::

:::{note}
Expand Down Expand Up @@ -72,3 +76,69 @@ important behaviors of the target are:
* It provides a single output file OR it provides an executable output; this
output is treated as the coverage entry point.
* If it provides runfiles, then `runfiles.files` are included into `py_test`.

(coverage-from-pypi)=
## Using `coverage` from PyPI

To use the version of `coverage` that is locked in your requirements instead of
the one bundled with `rules_python`, add it to your requirements and set the
{flag}`--coverage` flag to the `coverage` package in your {obj}`pip.parse` hub:

```
# .bazelrc
coverage --@rules_python//python/config_settings:coverage=@pypi//coverage
```

The Python toolchains don't need to be configured. The target is added to the
dependencies of the `py_test` and `py_binary` targets when coverage is
collected, and it isn't fetched for regular builds.

### Using a `.coveragerc` and plugins

To configure `coverage`, wrap it in a `py_library` together with any plugins and
the `.coveragerc` file, and set the {flag}`--coverage` flag to it:

```starlark
py_library(
name = "coverage",
data = [".coveragerc"],
deps = [
"@pypi//coverage",
"@pypi//coverage_conditional_plugin",
],
)
```

```
# .bazelrc
coverage --@rules_python//python/config_settings:coverage=//:coverage
```

The `.coveragerc` files in the runfiles of the target are merged in order:
options that are lists (e.g. `omit`, `exclude_also` or `plugins`) are combined
and the other options are overridden. The options that Bazel needs, such as
`relative_files`, `source` and `branch`, are always set by `rules_python`.

### Using a different `coverage` for some tests

The {flag}`--coverage` flag can be set for a single target with the
`config_settings` attribute:

```starlark
py_test(
name = "strict_test",
srcs = ["strict_test.py"],
config_settings = {
"@rules_python//python/config_settings:coverage": str(Label("//tools:coverage_strict")),
},
)
```

:::{note}
Use `str(Label(...))` for the value, so that the label is resolved relative to
your repository. This builds the test and its dependencies in a separate
configuration.
:::

:::{versionadded} VERSION_NEXT_FEATURE
:::
6 changes: 6 additions & 0 deletions news/4433.added.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
(coverage) Added the {flag}`--coverage` flag to use the `coverage` package
locked in the requirements, e.g. `@pypi//coverage`, without configuring the
Python toolchains. It can be a `py_library` that bundles plugins and
`.coveragerc` files, which are merged, and it can be set per target via
`config_settings`
([#3902](https://github.com/bazel-contrib/rules_python/issues/3902)).
6 changes: 6 additions & 0 deletions python/config_settings/BUILD.bazel
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,12 @@ rp_string_flag(
visibility = NOT_ACTUALLY_PUBLIC,
)

label_flag(
name = "coverage",
build_setting_default = "//python/private:empty",
visibility = ["//visibility:public"],
)

label_flag(
name = "debugger",
build_setting_default = "//python/private:empty",
Expand Down
28 changes: 28 additions & 0 deletions python/private/BUILD.bazel
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,34 @@ alias(
visibility = ["//visibility:public"],
)

# The `coverage` flag is only resolved when collecting coverage for the target
# config, so that e.g. `@pypi//coverage` is not fetched for regular builds.
alias(
name = "coverage_if_target_config",
actual = select({
":is_bazel_config_mode_target": ":coverage_if_enabled",
"//conditions:default": "//python/private:empty",
}),
# Not actually public. Only public because it's an implicit dependency of
# rules built via py_binary_rule_builder() / py_test_rule_builder().
visibility = ["//visibility:public"],
)

alias(
name = "coverage_if_enabled",
actual = select({
":is_coverage_enabled": "//python/config_settings:coverage",
"//conditions:default": "//python/private:empty",
}),
visibility = ["//visibility:private"],
)

config_setting(
name = "is_coverage_enabled",
values = {"collect_code_coverage": "true"},
visibility = ["//visibility:private"],
)

bazel_config_mode(name = "bazel_config_mode")

# This should only be set by analysis tests to expose additional metadata to
Expand Down
1 change: 1 addition & 0 deletions python/private/common_labels.bzl
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ labels = struct(
BUILD_PYTHON_ZIP = str(Label("//python/config_settings:build_python_zip")),
# NOTE: Special target; see definition for details.
BUILD_RUNFILE_LINKS = str(Label("//command_line_option:build_runfile_links")),
COVERAGE = str(Label("//python/config_settings:coverage")),
DEBUGGER = str(Label("//python/config_settings:debugger")),
# NOTE: Special target; see definition for details.
ENABLE_RUNFILES = str(Label("//command_line_option:enable_runfiles")),
Expand Down
54 changes: 53 additions & 1 deletion python/private/py_executable.bzl
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,10 @@ accepting arbitrary Python versions.
allow_files = True,
cfg = "exec",
),
"_coverage_flag": lambda: attrb.Label(
default = "//python/private:coverage_if_target_config",
providers = [PyInfo],
),
"_debugger_flag": lambda: attrb.Label(
default = "//python/private:debugger_if_target_config",
providers = [PyInfo],
Expand Down Expand Up @@ -329,6 +333,7 @@ def _should_create_init_files(ctx):
def _create_executable(
ctx,
*,
coverage,
executable,
main_py,
imports,
Expand Down Expand Up @@ -371,10 +376,12 @@ def _create_executable(
"1" if BootstrapImplFlag.get_value(ctx) == BootstrapImplFlag.SYSTEM_PYTHON else "0"
),
extra_deps = extra_deps,
coverage = coverage,
)

stage2_bootstrap = _create_stage2_bootstrap(
ctx,
coverage = coverage,
output_prefix = base_executable_name,
output_sibling = executable,
main_py = main_py,
Expand Down Expand Up @@ -575,7 +582,7 @@ def _create_zip_main(ctx, *, stage2_bootstrap, runtime_details, venv):
# * https://snarky.ca/how-virtual-environments-work/
# * https://github.com/python/cpython/blob/main/Modules/getpath.py
# * https://github.com/python/cpython/blob/main/Lib/site.py
def _create_venv(ctx, output_prefix, imports, runtime_details, add_runfiles_root_to_sys_path, extra_deps):
def _create_venv(ctx, output_prefix, imports, runtime_details, add_runfiles_root_to_sys_path, extra_deps, coverage):
venv_ctx_rel_root = "_{}.venv".format(output_prefix.lstrip("_"))
runtime = runtime_details.effective_runtime
if runtime.interpreter:
Expand Down Expand Up @@ -612,6 +619,7 @@ def _create_venv(ctx, output_prefix, imports, runtime_details, add_runfiles_root
output = site_init,
substitutions = {
"%add_runfiles_root_to_sys_path%": add_runfiles_root_to_sys_path,
"%coverage_from_deps%": "1" if coverage.from_deps else "0",
"%coverage_tool%": _get_coverage_tool_runfiles_path(ctx, runtime),
"%import_all%": "True" if read_possibly_native_flag(ctx, "python_import_all_repositories") else "False",
"%interpreter_actual_path%": interpreter_actual_path,
Expand Down Expand Up @@ -895,6 +903,40 @@ def _venv_details(
def _map_each_identity(v):
return v

def _get_coverage_details(ctx):
"""Returns how the `coverage` package is provided to the executable.

The {obj}`--coverage` flag, which can also be set per target via
`config_settings`, takes precedence over the `coverage_tool` of the Python
runtime, which is handled by the bootstrap.

Args:
ctx: {type}`ctx` the rule ctx.

Returns:
{type}`struct` with attributes:
* dep: {type}`Target | None` the `coverage` flag target to add to the
dependencies of the executable.
* from_deps: {type}`bool` whether `coverage` is importable from the
flag target, so that the runtime `coverage_tool` is not needed.
* rcfiles: {type}`list[File]` the `.coveragerc` files to merge.
"""
if not ctx.configuration.coverage_enabled or _is_tool_config(ctx):
return struct(dep = None, from_deps = False, rcfiles = [])

# The flag defaults to an empty `py_library`, which has no sources.
target = ctx.attr._coverage_flag
if target[PyInfo].transitive_sources:
rcfiles = [
f
for f in target[DefaultInfo].default_runfiles.files.to_list()
# Skip any `.coveragerc` shipped inside of a wheel.
if f.basename == ".coveragerc" and "/site-packages/" not in f.short_path
]
return struct(dep = target, from_deps = True, rcfiles = rcfiles)

return struct(dep = None, from_deps = False, rcfiles = [])

def _get_coverage_tool_runfiles_path(ctx, runtime):
if (ctx.configuration.coverage_enabled and
runtime and
Expand All @@ -906,6 +948,7 @@ def _get_coverage_tool_runfiles_path(ctx, runtime):
def _create_stage2_bootstrap(
ctx,
*,
coverage,
output_prefix,
output_sibling,
main_py,
Expand Down Expand Up @@ -934,6 +977,10 @@ def _create_stage2_bootstrap(
substitutions = {
"%build_data_file%": runfiles_root_path(ctx, build_data_file.short_path),
"%coverage_instrumented%": str(int(ctx.configuration.coverage_enabled and ctx.coverage_instrumented())),
"%coverage_rcfiles%": ":".join([
runfiles_root_path(ctx, f.short_path)
for f in coverage.rcfiles
]),
"%coverage_tool%": _get_coverage_tool_runfiles_path(ctx, runtime),
"%import_all%": "True" if read_possibly_native_flag(ctx, "python_import_all_repositories") else "False",
"%imports%": ":".join(imports.to_list()),
Expand Down Expand Up @@ -1270,6 +1317,10 @@ def py_executable_base_impl(ctx, *, semantics, is_test, inherited_environment =
if not _is_tool_config(ctx):
extra_deps.append(ctx.attr._debugger_flag)

coverage = _get_coverage_details(ctx)
if coverage.dep:
extra_deps.append(coverage.dep)

imports = collect_imports(ctx, extra_deps = extra_deps)
runtime_details = _get_runtime_details(ctx)
cc_details = _get_cc_details_for_binary(ctx, extra_deps = extra_deps)
Expand All @@ -1295,6 +1346,7 @@ def py_executable_base_impl(ctx, *, semantics, is_test, inherited_environment =
)
exec_result = _create_executable(
ctx,
coverage = coverage,
executable = executable,
main_py = main_py,
imports = imports,
Expand Down
15 changes: 15 additions & 0 deletions python/private/py_runtime_info.bzl
Original file line number Diff line number Diff line change
Expand Up @@ -305,8 +305,17 @@ are (only) `"PY2"` and `"PY3"`.
The template to use for the binary-specific site-init hook run by the
interpreter at startup.

The following substitutions are made during template expansion:
* `%coverage_from_deps%`: The string `1` if coverage is enabled and the
`coverage` package is importable from the dependencies (see
{flag}`--coverage`). The string `0` otherwise.

:::{versionadded} 1.0.0
:::

:::{versionchanged} VERSION_NEXT_FEATURE
Added the `%coverage_from_deps%` substitution.
:::
""",
"stage2_bootstrap_template": """
:type: File
Expand All @@ -322,6 +331,8 @@ The following substitutions are made during template expansion:
can be a `.py` or `.pyc` file, depending on precompile settings.
* `%coverage_tool%`: Runfiles-relative path to the coverage library's entry point.
If coverage is not enabled or available, an empty string.
* `%coverage_rcfiles%`: A colon-delimited string of runfiles-relative paths to
the `.coveragerc` files to merge. See {flag}`--coverage`.
* `%import_all%`: The string `True` if all repositories in the runfiles should
be added to sys.path. The string `False` otherwise.
* `%imports%`: A colon-delimited string of runfiles-relative paths to add to
Expand All @@ -331,6 +342,10 @@ The following substitutions are made during template expansion:

:::{versionadded} 0.33.0
:::

:::{versionchanged} VERSION_NEXT_FEATURE
Added the `%coverage_rcfiles%` substitution.
:::
""",
"stub_shebang": """
:type: str
Expand Down
5 changes: 4 additions & 1 deletion python/private/py_runtime_rule.bzl
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,10 @@ def coverage_tool_missing_message(*, coverage_enabled, coverage_tool, label):
======================================================================
WARNING: Python runtime {label} has no coverage_tool.
`bazel coverage` will produce empty lcov data for py_test targets that
resolve to this runtime.
resolve to this runtime, unless they get `coverage` from their deps.

To use the `coverage` locked in your requirements, set e.g.:
--@rules_python//python/config_settings:coverage=@pypi//coverage

For rules_python's hermetic toolchains, enable the bundled coverage.py:
python.toolchain(configure_coverage_tool = True) # bzlmod
Expand Down
8 changes: 8 additions & 0 deletions python/private/site_init_template.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@
_SELF_RUNFILES_RELATIVE_PATH = "%site_init_runfiles_path%"
# Runfiles-relative path to the coverage tool entry point, if any.
_COVERAGE_TOOL = "%coverage_tool%"
# True if the coverage package is importable from the dependencies, i.e. when
# --@rules_python//python/config_settings:coverage is set.
_COVERAGE_FROM_DEPS = "%coverage_from_deps%" == "1"
# True if the runfiles root should be added to sys.path
_ADD_RUNFILES_ROOT_TO_SYS_PATH = "%add_runfiles_root_to_sys_path%" == "1"
_INTERPRETER_ACTUAL_PATH = "%interpreter_actual_path%"
Expand All @@ -53,6 +56,7 @@ def _print_verbose(*args, mapping=None, values=None):
_print_verbose("workspace_name:", _WORKSPACE_NAME)
_print_verbose("self_runfiles_path:", _SELF_RUNFILES_RELATIVE_PATH)
_print_verbose("coverage_tool:", _COVERAGE_TOOL)
_print_verbose("coverage_from_deps:", _COVERAGE_FROM_DEPS)
_print_verbose("interpreter_actual_path:", _INTERPRETER_ACTUAL_PATH)


Expand Down Expand Up @@ -210,6 +214,10 @@ def _maybe_add_path(path, reason):
# NOTE: Coverage is added last to allow user dependencies to override it.
coverage_setup = False
if os.environ.get("COVERAGE_DIR"):
if _COVERAGE_FROM_DEPS:
# The import paths were already added along with the other deps.
_print_verbose_coverage("Using coverage from deps")
return True
cov_tool = _COVERAGE_TOOL
if cov_tool:
_print_verbose_coverage(f"Using toolchain coverage_tool {cov_tool}")
Expand Down
Loading
Loading