feat(toolchains): let local toolchains point to a label (#3304)

Currently, the local toolchain code requires using a path (or program
name) to find
the Python interpreter. This comes up short when using Bazel to
download an arbitrary runtime (or otherwise manage the creation of it,
e.g.
downloading Python and building it from source in a repo rule). In such
cases, the
file system location of the interpreter isn't known (it'll be in some
Bazel cache
directory).

To fix, add the `interpreter_target` attribute to `local_runtime_repo`,
which it
looks up the path for, then continues on as normal. As an example, the
test uses
a custom repository rule to download a particular version of Python
appropriate
to the OS.

Author: rickeylev

CHANGELOG.md

@@ -109,6 +109,7 @@ END_UNRELEASED_TEMPLATE
     {obj}`py_cc_toolchain.headers_abi3`, and {obj}`PyCcToolchainInfo.headers_abi3`.
   * {obj}`//python:features.bzl%features.headers_abi3` can be used to
     feature-detect the presense of the above.
+* (toolchains) Local toolchains can use a label for the interpreter to use.
 
 {#v1-6-3}
 ## [1.6.3] - 2025-09-21

docs/toolchains.md

@@ -460,6 +460,10 @@ local_runtime_toolchains_repo(
 register_toolchains("@local_toolchains//:all", dev_dependency = True)
 ```
 
+In the example above, `interpreter_path` is used to find Python via `PATH`
+lookups. Alternatively, {obj}`interpreter_target` can be set, which can
+refer to a Python in an arbitrary Bazel repository.
+
 :::{important}
 Be sure to set `dev_dependency = True`. Using a local toolchain only makes sense
 for the root module.

python/private/local_runtime_repo.bzl

@@ -200,13 +200,37 @@ a system having the necessary Python installed.
             doc = """
 An absolute path or program name on the `PATH` env var.
 
+*Mutually exclusive with `interpreter_target`.*
+
 Values with slashes are assumed to be the path to a program. Otherwise, it is
 treated as something to search for on `PATH`
 
 Note that, when a plain program name is used, the path to the interpreter is
 resolved at repository evalution time, not runtime of any resulting binaries.
+
+If not set, defaults to `python3`.
+
+:::{seealso}
+The {obj}`interpreter_target` attribute for getting the interpreter from
+a label
+:::
+""",
+            default = "",
+        ),
+        "interpreter_target": attr.label(
+            doc = """
+A label to a Python interpreter executable.
+
+*Mutually exclusive with `interpreter_path`.*
+
+On Windows, if the path doesn't exist, various suffixes will be tried to
+find a usable path.
+
+:::{seealso}
+The {obj}`interpreter_path` attribute for getting the interpreter from
+a path or PATH environment lookup.
+:::
 """,
-            default = "python3",
         ),
         "on_failure": attr.string(
             default = _OnFailure.SKIP,
@@ -247,6 +271,37 @@ def _expand_incompatible_template():
         os = "@platforms//:incompatible",
     )
 
+def _find_python_exe_from_target(rctx):
+    base_path = rctx.path(rctx.attr.interpreter_target)
+    if base_path.exists:
+        return base_path, None
+    attempted_paths = [base_path]
+
+    # Try to convert a unix-y path to a Windows path. On Linux/Mac,
+    # the path is usually `bin/python3`. On Windows, it's simply
+    # `python.exe`.
+    basename = base_path.basename.rstrip("3")
+    path = base_path.dirname.dirname.get_child(basename)
+    path = rctx.path("{}.exe".format(path))
+    if path.exists:
+        return path, None
+    attempted_paths.append(path)
+
+    # Try adding .exe to the base path
+    path = rctx.path("{}.exe".format(base_path))
+    if path.exists:
+        return path, None
+    attempted_paths.append(path)
+
+    describe_failure = lambda: (
+        "Target '{target}' could not be resolved to a valid path. " +
+        "Attempted paths: {paths}"
+    ).format(
+        target = rctx.attr.interpreter_target,
+        paths = "\n".join([str(p) for p in attempted_paths]),
+    )
+    return None, describe_failure
+
 def _resolve_interpreter_path(rctx):
     """Find the absolute path for an interpreter.
 
@@ -260,20 +315,27 @@ def _resolve_interpreter_path(rctx):
           returns a description of why it couldn't be resolved
         A path object or None. The path may not exist.
     """
-    if "/" not in rctx.attr.interpreter_path and "\\" not in rctx.attr.interpreter_path:
-        # Provide a bit nicer integration with pyenv: recalculate the runtime if the
-        # user changes the python version using e.g. `pyenv shell`
-        repo_utils.getenv(rctx, "PYENV_VERSION")
-        result = repo_utils.which_unchecked(rctx, rctx.attr.interpreter_path)
-        resolved_path = result.binary
-        describe_failure = result.describe_failure
+    if rctx.attr.interpreter_path and rctx.attr.interpreter_target:
+        fail("interpreter_path and interpreter_target are mutually exclusive")
+
+    if rctx.attr.interpreter_target:
+        resolved_path, describe_failure = _find_python_exe_from_target(rctx)
     else:
-        rctx.watch(rctx.attr.interpreter_path)
-        resolved_path = rctx.path(rctx.attr.interpreter_path)
-        if not resolved_path.exists:
-            describe_failure = lambda: "Path not found: {}".format(repr(rctx.attr.interpreter_path))
+        interpreter_path = rctx.attr.interpreter_path or "python3"
+        if "/" not in interpreter_path and "\\" not in interpreter_path:
+            # Provide a bit nicer integration with pyenv: recalculate the runtime if the
+            # user changes the python version using e.g. `pyenv shell`
+            repo_utils.getenv(rctx, "PYENV_VERSION")
+            result = repo_utils.which_unchecked(rctx, interpreter_path)
+            resolved_path = result.binary
+            describe_failure = result.describe_failure
         else:
-            describe_failure = None
+            rctx.watch(interpreter_path)
+            resolved_path = rctx.path(interpreter_path)
+            if not resolved_path.exists:
+                describe_failure = lambda: "Path not found: {}".format(repr(interpreter_path))
+            else:
+                describe_failure = None
 
     return struct(
         resolved_path = resolved_path,

tests/integration/local_toolchains/BUILD.bazel

@@ -18,19 +18,37 @@ load("@rules_python//python:py_test.bzl", "py_test")
 load(":py_extension.bzl", "py_extension")
 
 py_test(
-    name = "test",
-    srcs = ["test.py"],
+    name = "local_runtime_test",
+    srcs = ["local_runtime_test.py"],
+    config_settings = {
+        "//:py": "local",
+    },
     # Make this test better respect pyenv
     env_inherit = ["PYENV_VERSION"],
 )
 
+py_test(
+    name = "repo_runtime_test",
+    srcs = ["repo_runtime_test.py"],
+    config_settings = {
+        "//:py": "repo",
+    },
+)
+
 config_setting(
     name = "is_py_local",
     flag_values = {
         ":py": "local",
     },
 )
 
+config_setting(
+    name = "is_py_repo",
+    flag_values = {
+        ":py": "repo",
+    },
+)
+
 # Set `--//:py=local` to use the local toolchain
 # (This is set in this example's .bazelrc)
 string_flag(

tests/integration/local_toolchains/MODULE.bazel

@@ -23,32 +23,76 @@ local_path_override(
     path = "../../..",
 )
 
+# Step 1: Define the python runtime
 local_runtime_repo = use_repo_rule("@rules_python//python/local_toolchains:repos.bzl", "local_runtime_repo")
 
 local_runtime_toolchains_repo = use_repo_rule("@rules_python//python/local_toolchains:repos.bzl", "local_runtime_toolchains_repo")
 
+# This will use `python3` from the environment
 local_runtime_repo(
     name = "local_python3",
     interpreter_path = "python3",
     on_failure = "fail",
 )
 
+pbs_archive = use_repo_rule("//:pbs_archive.bzl", "pbs_archive")
+
+pbs_archive(
+    name = "pbs_runtime",
+    sha256 = {
+        "linux": "0a01bad99fd4a165a11335c29eb43015dfdb8bd5ba8e305538ebb54f3bf3146d",
+        "mac os x": "4fb42ffc8aad2a42ca7646715b8926bc6b2e0d31f13d2fec25943dc236a6fd60",
+        "windows": "005cb2abf4cfa4aaa48fb10ce4e33fe4335ea4d1f55202dbe4e20c852e45e0f9",
+    },
+    urls = {
+        "linux": "https://github.com/astral-sh/python-build-standalone/releases/download/20250918/cpython-3.13.7+20250918-x86_64-unknown-linux-gnu-install_only.tar.gz",
+        "mac os x": "https://github.com/astral-sh/python-build-standalone/releases/download/20250918/cpython-3.13.7+20250918-x86_64-apple-darwin-install_only.tar.gz",
+        "windows server 2022": "https://github.com/astral-sh/python-build-standalone/releases/download/20250918/cpython-3.13.7+20250918-x86_64-pc-windows-msvc-install_only.tar.gz",
+    },
+)
+
+# This will use Python from the `pbs_runtime` repository.
+# The pbs_runtime is just an example; the repo just needs to be a valid Python
+# installation.
+local_runtime_repo(
+    name = "repo_python3",
+    interpreter_target = "@pbs_runtime//:python/bin/python",
+    on_failure = "fail",
+)
+
+# Step 2: Create toolchains for the runtimes
+# Below, we configure them to only activate if the `//:py` flag has particular
+# values.
 local_runtime_toolchains_repo(
     name = "local_toolchains",
-    runtimes = ["local_python3"],
+    runtimes = [
+        "local_python3",
+        "repo_python3",
+    ],
     target_compatible_with = {
         "local_python3": [
             "HOST_CONSTRAINTS",
         ],
+        "repo_python3": [
+            "HOST_CONSTRAINTS",
+        ],
     },
     target_settings = {
         "local_python3": [
             "@//:is_py_local",
         ],
+        "repo_python3": [
+            "@//:is_py_repo",
+        ],
     },
 )
 
+config = use_extension("@rules_python//python/extensions:config.bzl", "config")
+config.add_transition_setting(setting = "//:py")
+
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.toolchain(python_version = "3.13")
 use_repo(python, "rules_python_bzlmod_debug")
 
+# Step 3: Register the toolchains
 register_toolchains("@local_toolchains//:all")

tests/integration/local_toolchains/WORKSPACE

@@ -9,7 +9,11 @@ local_repository(
 
 load("@rules_python//python:repositories.bzl", "py_repositories")
 
-py_repositories()
+py_repositories(
+    transition_settings = [
+        "@//:py",
+    ],
+)
 
 load("@rules_python//python/local_toolchains:repos.bzl", "local_runtime_repo", "local_runtime_toolchains_repo")
 
@@ -21,10 +25,51 @@ local_runtime_repo(
     # or interpreter_path = "C:\\path\\to\\python.exe"
 )
 
+load("//:pbs_archive.bzl", "pbs_archive")
+
+pbs_archive(
+    name = "pbs_runtime",
+    sha256 = {
+        "linux": "0a01bad99fd4a165a11335c29eb43015dfdb8bd5ba8e305538ebb54f3bf3146d",
+        "mac os x": "4fb42ffc8aad2a42ca7646715b8926bc6b2e0d31f13d2fec25943dc236a6fd60",
+        "windows": "005cb2abf4cfa4aaa48fb10ce4e33fe4335ea4d1f55202dbe4e20c852e45e0f9",
+    },
+    urls = {
+        "linux": "https://github.com/astral-sh/python-build-standalone/releases/download/20250918/cpython-3.13.7+20250918-x86_64-unknown-linux-gnu-install_only.tar.gz",
+        "mac os x": "https://github.com/astral-sh/python-build-standalone/releases/download/20250918/cpython-3.13.7+20250918-x86_64-apple-darwin-install_only.tar.gz",
+        "windows server 2022": "https://github.com/astral-sh/python-build-standalone/releases/download/20250918/cpython-3.13.7+20250918-x86_64-pc-windows-msvc-install_only.tar.gz",
+    },
+)
+
+local_runtime_repo(
+    name = "repo_python3",
+    interpreter_target = "@pbs_runtime//:python/bin/python3",
+    on_failure = "fail",
+)
+
 # Step 2: Create toolchains for the runtimes
 local_runtime_toolchains_repo(
     name = "local_toolchains",
-    runtimes = ["local_python3"],
+    runtimes = [
+        "local_python3",
+        "repo_python3",
+    ],
+    target_compatible_with = {
+        "local_python3": [
+            "HOST_CONSTRAINTS",
+        ],
+        "repo_python3": [
+            "HOST_CONSTRAINTS",
+        ],
+    },
+    target_settings = {
+        "local_python3": [
+            "@//:is_py_local",
+        ],
+        "repo_python3": [
+            "@//:is_py_repo",
+        ],
+    },
 )
 
 # Step 3: Register the toolchains

tests/integration/local_toolchains/test.py renamed to tests/integration/local_toolchains/local_runtime_test.py

@@ -0,0 +1,53 @@
+"""A repository rule to download and extract a Python runtime archive."""
+
+BUILD_BAZEL = """
+# Generated by pbs_archive.bzl
+
+package(
+    default_visibility = ["//visibility:public"],
+)
+
+exports_files(glob(["**"]))
+"""
+
+def _pbs_archive_impl(repository_ctx):
+    """Implementation of the python_build_standalone_archive rule."""
+    os_name = repository_ctx.os.name.lower()
+    urls = repository_ctx.attr.urls
+    sha256s = repository_ctx.attr.sha256
+
+    if os_name not in urls:
+        fail("Unsupported OS: '{}'. Available OSs are: {}".format(
+            os_name,
+            ", ".join(urls.keys()),
+        ))
+
+    url = urls[os_name]
+    sha256 = sha256s.get(os_name, "")
+
+    repository_ctx.download_and_extract(
+        url = url,
+        sha256 = sha256,
+    )
+
+    repository_ctx.file("BUILD.bazel", BUILD_BAZEL)
+
+pbs_archive = repository_rule(
+    implementation = _pbs_archive_impl,
+    attrs = {
+        "sha256": attr.string_dict(
+            doc = "A dictionary of SHA256 checksums for the archives, keyed by OS name.",
+            mandatory = True,
+        ),
+        "urls": attr.string_dict(
+            doc = "A dictionary of URLs to the runtime archives, keyed by OS name (e.g., 'linux', 'windows').",
+            mandatory = True,
+        ),
+    },
+    doc = """
+Downloads and extracts a Python runtime archive for the current OS.
+
+This rule selects a URL from the `urls` attribute based on the host OS,
+downloads the archive, and extracts it.
+""",
+)

tests/integration/local_toolchains/pbs_archive.bzl

@@ -0,0 +1,19 @@
+import os.path
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+
+class RepoToolchainTest(unittest.TestCase):
+    maxDiff = None
+
+    def test_python_from_repo_used(self):
+        actual = os.path.realpath(sys._base_executable.lower())
+        # Normalize case: Windows may have case differences
+        self.assertIn("pbs_runtime", actual.lower())
+
+
+if __name__ == "__main__":
+    unittest.main()