cleanup and fix

Author: rickeylev

docs/toolchains.md

@@ -418,8 +418,8 @@ The two settings to change are
 {obj}`local_runtime_toolchains_repo.target_compatible_with` and
 {obj}`local_runtime_toolchains_repo.target_settings`, which control how Bazel
 decides if a toolchain should match. By default, they point to targets *within*
-the local runtime repository. We have to override them to *not* reference the
-local runtime repository at all.
+the local runtime repository (trigger repo initialization). We have to override
+them to *not* reference the local runtime repository at all.
 
 In the example below, we reconfigure the local toolchains so they are only
 activated if the custom flag `--//:py=local` is set and the target platform
@@ -438,35 +438,27 @@ local_runtime_toolchains_repo(
         "local_python3": ["HOST_CONSTRAINTS"],
     },
     target_settings = {
-        "local_python3": ["@//:is_local_py_enabled"]
+        "local_python3": ["@//:is_py_local"]
     }
 )
 
 # File: BUILD.bazel
 load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
 
-alias(
-    name = "is_local_py_enabled",
-    actual = select({
-        ":_is_py_local_set": "@local_python3//:is_matching_python_version",
-        "//conditions:default": ":_does_not_match",
-    }),
-)
-
 config_setting(
-    name = "_is_py_local_set",
+    name = "is_py_local",
     flag_values = {":py": "local"},
 )
 
-config_setting(
-    name = "_does_not_match",
-    flag_values = {":py": "<DOES NOT MATCH>"},
+string_flag(
+    name = "py",
+    build_setting_default = "",
 )
-
 ```
 
 :::{tip}
-With some minor changes, different values for the `--//:py` flag can be used
+Easily switching between *multiple* local toolchains can be accomplished by
+adding additional `:is_py_X` targets and setting `--//:py` to match.
 to easily switch between different local toolchains.
 :::
 
@@ -498,7 +490,7 @@ locally installed Python.
 ### Autodetecting toolchain
 
 The autodetecting toolchain is a deprecated toolchain that is built into Bazel.
-It's name is a bit misleading: it doesn't autodetect anything. All it does is
+**It's name is a bit misleading: it doesn't autodetect anything**. All it does is
 use `python3` from the environment a binary runs within. This provides extremely
 limited functionality to the rules (at build time, nothing is knowable about
 the Python runtime).

python/private/local_runtime_toolchains_repo.bzl

@@ -167,9 +167,10 @@ needed because the strings are evaluated in a different context than where
 they originate.
 :::
 
-The list of settings are **becomes the** {obj}`toolchain.target_settings` value
-for each respective repo; i.e. they replace the auto-detected values the
-local runtime itself computes.
+The list of settings will be applied atop of any of the local runtime's
+settings that are used for {obj}`toolchain.target_settings`. i.e. they are
+evaluated first and guard the checking of the local runtime's auto-detected
+conditions.
 
 This allows a local toolchain to only be used if certain flags or
 config setting conditions are met. Such conditions can include user-defined

python/private/py_toolchain_suite.bzl

@@ -184,14 +184,22 @@ def define_local_toolchain_suites(
 
     i = 0
     for i, repo in enumerate(version_aware_repo_names, start = i):
+        target_settings = ["@{}//:is_matching_python_version".format(repo)]
+
+        if repo_target_settings.get(repo):
+            selects.config_setting_group(
+                name = "_{}_user_guard".format(repo),
+                match_all = repo_target_settings.get(repo, []) + target_settings,
+            )
+            target_settings = ["_{}_user_guard".format(repo)]
         _internal_toolchain_suite(
             prefix = render.left_pad_zero(i, 4),
             runtime_repo_name = repo,
             target_compatible_with = _get_local_toolchain_target_compatible_with(
                 repo,
                 repo_target_compatible_with,
             ),
-            target_settings = _get_local_toolchain_target_settings(repo, repo_target_settings),
+            target_settings = target_settings,
             exec_compatible_with = repo_exec_compatible_with.get(repo, []),
         )
 
@@ -211,13 +219,6 @@ def define_local_toolchain_suites(
             exec_compatible_with = repo_exec_compatible_with.get(repo, []),
         )
 
-def _get_local_toolchain_target_settings(repo, repo_target_settings):
-    if repo in repo_target_settings:
-        target_settings = repo_target_settings[repo]
-    else:
-        target_settings = ["@{}//:is_matching_python_version".format(repo)]
-    return target_settings
-
 def _get_local_toolchain_target_compatible_with(repo, repo_target_compatible_with):
     if repo in repo_target_compatible_with:
         target_compatible_with = repo_target_compatible_with[repo]

tests/integration/local_toolchains/BUILD.bazel

@@ -15,38 +15,22 @@
 load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
 load("@rules_python//python:py_test.bzl", "py_test")
 
-package(default_visibility = ["//visibility:public"])
-
 py_test(
     name = "test",
     srcs = ["test.py"],
     # Make this test better respect pyenv
     env_inherit = ["PYENV_VERSION"],
 )
 
-alias(
-    name = "is_local_py_enabled",
-    actual = select({
-        ":_is_py_local_set": "@local_python3//:is_matching_python_version",
-        "//conditions:default": ":_does_not_match",
-    }),
-)
-
 config_setting(
-    name = "_is_py_local_set",
+    name = "is_py_local",
     flag_values = {
         ":py": "local",
     },
 )
 
-config_setting(
-    name = "_does_not_match",
-    flag_values = {
-        ":py": "<DOES NOT MATCH>",
-    },
-)
-
-# set to "local" to use the local toolchain
+# Set `--//:py=local` to use the local toolchain
+# (This is set in this example's .bazelrc)
 string_flag(
     name = "py",
     build_setting_default = "",

tests/integration/local_toolchains/MODULE.bazel

@@ -42,7 +42,7 @@ local_runtime_toolchains_repo(
     },
     target_settings = {
         "local_python3": [
-            "@//:is_local_py_enabled",
+            "@//:is_py_local",
         ],
     },
 )