feat(toolchains): add add_target_settings to python.override (bazel-contrib#3731)

Users who register custom toolchain families (e.g. gated behind a
string_flag like "custom" vs "prebuilt") have no way to prevent the
default-registered toolchains from acting as a silent fallback. When a
user requests a custom toolchain at a version they didn't register,
Bazel's toolchain resolution quietly falls back to the default prebuilt
toolchain instead of producing an error.

This adds a `toolchain_target_settings` attribute to `python.override`
that appends the given `config_setting` labels to the `target_settings`
of every toolchain registered by the module extension:

```starlark
python.override(
    toolchain_target_settings = ["@@//:python_toolchain_family_prebuilt"],
)
```

These settings are appended to the `target_settings` of all toolchains
registered by the extension, including any that already have settings
from `python.single_version_platform_override`. Toolchains registered
outside the extension (e.g. via `local_runtime_toolchains_repo`) are not
affected.

Note: `toolchain_target_settings` is popped from the config `default`
dict before it reaches `python_register_toolchains()`, so it doesn't
leak into the `python_repository` kwargs.

Integration test passes across the full Bazel version matrix (7.7.0,
8.5.1, 9.0.0rc1). Verified the test fails without the fix (default
toolchain silently resolves as fallback).

Fixes bazel-contrib#3673

---------

Co-authored-by: Richard Levasseur <rlevasseur@google.com>

Author: novas0x2a

.bazelignore

@@ -33,3 +33,4 @@ sphinxdocs
 tests/integration/compile_pip_requirements/bazel-compile_pip_requirements
 tests/integration/local_toolchains/bazel-local_toolchains
 tests/integration/py_cc_toolchain_registered/bazel-py_cc_toolchain_registered
+tests/integration/toolchain_target_settings/bazel-module_under_test

.bazelrc.deleted_packages

@@ -36,6 +36,7 @@ common --deleted_packages=tests/integration/local_toolchains
 common --deleted_packages=tests/integration/pip_parse
 common --deleted_packages=tests/integration/pip_parse/empty
 common --deleted_packages=tests/integration/py_cc_toolchain_registered
+common --deleted_packages=tests/integration/toolchain_target_settings
 common --deleted_packages=tests/modules/another_module
 common --deleted_packages=tests/modules/other
 common --deleted_packages=tests/modules/other/nspkg_delta

CHANGELOG.md

@@ -68,6 +68,8 @@ END_UNRELEASED_TEMPLATE
 
 {#v0-0-0-added}
 ### Added
+* (toolchain) Added {obj}`python.override.toolchain_target_settings` to allow
+  adding `config_setting` labels to all registered toolchains.
 * (windows) Full venv support for Windows is available. Set
   {obj}`--venvs_site_packages=yes` to enable.
 * (runfiles) Added a pathlib-compatible API: {obj}`Runfiles.root()`

python/private/python.bzl

@@ -403,6 +403,10 @@ def _python_impl(module_ctx):
     # the PLATFORMS global for this toolchain
     toolchain_platform_keys = {}
 
+    # Extra target_settings to add to every registered toolchain, e.g. for
+    # gating the default toolchains behind a custom config_setting.
+    global_add_target_settings = py.config.add_target_settings
+
     # Split the toolchain info into separate objects so they can be passed onto
     # the repository rule.
     for entry in toolchain_impls:
@@ -414,7 +418,7 @@ def _python_impl(module_ctx):
 
         # The target_settings attribute may not be present for users
         # patching python/versions.bzl.
-        toolchain_ts_map[key] = getattr(entry.platform, "target_settings", [])
+        toolchain_ts_map[key] = getattr(entry.platform, "target_settings", []) + global_add_target_settings
         toolchain_platform_keys[key] = entry.platform_name
         toolchain_python_versions[key] = entry.full_python_version
 
@@ -702,6 +706,9 @@ def _process_global_overrides(*, tag, default, _fail = fail):
 
         default["minor_mapping"] = tag.minor_mapping
 
+    if tag.add_target_settings:
+        default["add_target_settings"] = list(tag.add_target_settings)
+
     forwarded_attrs = sorted(AUTH_ATTRS) + [
         "base_url",
         "register_all_versions",
@@ -809,6 +816,7 @@ def _get_toolchain_config(*, modules, _fail = fail):
     )
 
     register_all_versions = default.pop("register_all_versions", False)
+    add_target_settings = default.pop("add_target_settings", [])
     kwargs = default.pop("kwargs", {})
 
     versions = {}
@@ -834,6 +842,7 @@ def _get_toolchain_config(*, modules, _fail = fail):
         minor_mapping = minor_mapping,
         default = default,
         register_all_versions = register_all_versions,
+        add_target_settings = add_target_settings,
     )
 
 def _compute_default_python_version(mctx):
@@ -1099,6 +1108,30 @@ _override = tag_class(
 :::
 """,
     attrs = {
+        "add_target_settings": attr.string_list(
+            mandatory = False,
+            doc = """\
+A list of `config_setting` labels to add to the `target_settings` of every
+toolchain registered by this module extension. This is useful for creating
+separate "families" of toolchains gated behind custom build settings.
+
+For example, to ensure the default prebuilt toolchains are only resolved when
+a `prebuilt` config setting is active:
+
+```starlark
+python.override(
+    add_target_settings = ["@@//:python_toolchain_family_prebuilt"],
+)
+```
+
+These settings are appended to the `target_settings` of all toolchains
+registered by the extension, including any that already have settings
+from `python.single_version_platform_override`.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
+""",
+        ),
         "available_python_versions": attr.string_list(
             mandatory = False,
             doc = """\

tests/integration/BUILD.bazel

@@ -88,6 +88,11 @@ rules_python_integration_test(
     py_main = "custom_commands_test.py",
 )
 
+rules_python_integration_test(
+    name = "toolchain_target_settings_test",
+    py_main = "toolchain_target_settings_test.py",
+)
+
 py_library(
     name = "runner_lib",
     srcs = ["runner.py"],

tests/integration/toolchain_target_settings/.bazelrc

@@ -0,0 +1,3 @@
+common --lockfile_mode=off
+test --test_output=errors
+build --enable_runfiles

tests/integration/toolchain_target_settings/BUILD.bazel

@@ -0,0 +1,56 @@
+load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
+load("@rules_python//python:py_test.bzl", "py_test")
+
+# A flag to select which "family" of toolchains to use.
+string_flag(
+    name = "family",
+    build_setting_default = "prebuilt",
+    values = [
+        "prebuilt",
+        "custom",
+    ],
+)
+
+# Matches when the "prebuilt" family is selected.
+# This is referenced in MODULE.bazel's python.override(add_target_settings=...).
+config_setting(
+    name = "is_prebuilt",
+    flag_values = {
+        ":family": "prebuilt",
+    },
+)
+
+# Matches when the "custom" family is selected.
+# No toolchains use this setting, so selecting it should produce an error.
+config_setting(
+    name = "is_custom",
+    flag_values = {
+        ":family": "custom",
+    },
+)
+
+# This target selects the "prebuilt" family via config_settings transition.
+# Since python.override(add_target_settings = ["@@//:is_prebuilt"]) gates
+# the default toolchains, this should succeed: the flag matches, the config_setting
+# is satisfied, and the default 3.13 toolchain resolves.
+py_test(
+    name = "prebuilt_test",
+    srcs = ["main.py"],
+    config_settings = {
+        "//:family": "prebuilt",
+    },
+    main = "main.py",
+)
+
+# This target selects the "custom" family via config_settings transition.
+# No toolchains have target_settings = [":is_custom"], so toolchain resolution
+# should fail -- the default toolchains are gated behind ":is_prebuilt" and
+# won't match.
+py_test(
+    name = "custom_no_toolchain_test",
+    srcs = ["main.py"],
+    config_settings = {
+        "//:family": "custom",
+    },
+    main = "main.py",
+)

tests/integration/toolchain_target_settings/MODULE.bazel

@@ -0,0 +1,24 @@
+module(name = "module_under_test")
+
+bazel_dep(name = "rules_python", version = "0.0.0")
+bazel_dep(name = "bazel_skylib", version = "1.7.1")
+
+local_path_override(
+    module_name = "rules_python",
+    path = "../../..",
+)
+
+python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.toolchain(python_version = "3.13")
+
+# Gate ALL default-registered toolchains behind the "prebuilt" config setting.
+# This prevents them from being a silent fallback when a different toolchain
+# family is requested.
+python.override(
+    add_target_settings = ["@@//:is_prebuilt"],
+)
+
+# Register //:family as a transition setting so py_binary/py_test
+# config_settings can set it.
+config = use_extension("@rules_python//python/extensions:config.bzl", "config")
+config.add_transition_setting(setting = "//:family")

tests/integration/toolchain_target_settings/REPO.bazel

@@ -0,0 +1 @@
+# Intentionally blank; bzlmod is used.