feat(toolchains): add toolchain_target_settings to python.override

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.

Add 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. This lets users gate
the default toolchains behind a config_setting so they only resolve when
explicitly selected, giving a clean separation between toolchain
families.

Fixes #3673

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

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_toolchain_target_settings = py.config.toolchain_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_toolchain_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.toolchain_target_settings:
+        default["toolchain_target_settings"] = list(tag.toolchain_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)
+    toolchain_target_settings = default.pop("toolchain_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,
+        toolchain_target_settings = toolchain_target_settings,
     )
 
 def _compute_default_python_version(mctx):
@@ -1144,6 +1153,30 @@ The values in this mapping override the default values and do not replace them.
             default = {},
         ),
         "register_all_versions": attr.bool(default = False, doc = "Add all versions"),
+        "toolchain_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(
+    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`.
+
+:::{versionadded} VERSION_NEXT
+:::
+""",
+        ),
     } | AUTH_ATTRS,
 )
 

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,70 @@
+# Copyright 2025 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+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(toolchain_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(toolchain_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,37 @@
+# Copyright 2025 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+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(
+    toolchain_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.