feat: provide access to arbitrary interpreters

docs/toolchains.md

@@ -396,7 +396,7 @@ provide `Python.h`.
 
 This is typically implemented using {obj}`py_cc_toolchain()`, which provides
 {obj}`ToolchainInfo` with the field `py_cc_toolchain` set, which is a
-{obj}`PyCcToolchainInfo` provider instance. 
+{obj}`PyCcToolchainInfo` provider instance.
 
 This toolchain type is intended to hold only _target configuration_ values
 relating to the C/C++ information for the Python runtime. As such, when defining
@@ -556,4 +556,45 @@ of available toolchains.
 Currently the following flags are used to influence toolchain selection:
 * {obj}`--@rules_python//python/config_settings:py_linux_libc` for selecting the Linux libc variant.
 * {obj}`--@rules_python//python/config_settings:py_freethreaded` for selecting
-  the freethreaded experimental Python builds available from `3.13.0` onwards.
+  the freethreaded experimental Python builds available from `3.13.0` onwards.
+
+## Running the underlying interpreter
+
+To run the interpreter that Bazel will use, you can use the
+`@rules_python//python/bin:python` target. This is a binary target with
+the executable pointing at the `python3` binary plus its relevent runfiles.
+
+```console
+$ bazel run @rules_python//python/bin:python
+Python 3.11.1 (main, Jan 16 2023, 22:41:20) [Clang 15.0.7 ] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>>
+$ bazel run @rules_python//python/bin:python --@rules_python//python/config_settings:python_version=3.12
+Python 3.12.0 (main, Oct  3 2023, 01:27:23) [Clang 17.0.1 ] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>>
+```
+
+You can also access a specific binary's interpreter this way by using the
+`@rules_python//python/bin:python_src` target. In the example below, it is
+assumed that the `@rules_python//tools/publish:twine` binary is fixed at Python
+3.11.
+
+```console
+$ bazel run @rules_python//python/bin:python --@rules_python//python/bin:interpreter_src=@rules_python//tools/publish:twine
+Python 3.11.1 (main, Jan 16 2023, 22:41:20) [Clang 15.0.7 ] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>>
+$ bazel run @rules_python//python/bin:python --@rules_python//python/bin:interpreter_src=@rules_python//tools/publish:twine --@rules_python//python/config_settings:python_version=3.12
+Python 3.11.1 (main, Jan 16 2023, 22:41:20) [Clang 15.0.7 ] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>>
+```
+Despite setting the Python version explicitly to 3.12 in the example above, the
+interpreter comes from the `@rules_python//tools/publish:twine` binary. That is
+a fixed version.
+
+:::{note}
+The `python` target does not provide access to any modules from `py_*`
+targets on its own. Please file a feature request if this is desired.
+:::

python/BUILD.bazel

@@ -35,6 +35,7 @@ filegroup(
     name = "distribution",
     srcs = glob(["**"]) + [
         "//python/api:distribution",
+        "//python/bin:distribution",
         "//python/cc:distribution",
         "//python/config_settings:distribution",
         "//python/constraints:distribution",

python/bin/BUILD.bazel

@@ -0,0 +1,20 @@
+load("//python/private:interpreter.bzl", _interpreter_binary = "interpreter_binary")
+
+filegroup(
+    name = "distribution",
+    srcs = glob(["**"]),
+    visibility = ["//:__subpackages__"],
+)
+
+_interpreter_binary(
+    name = "python",
+    binary = ":python_src",
+    visibility = ["//visibility:public"],
+)
+
+# The user can modify this flag to source different interpreters for the
+# `python` target above.
+label_flag(
+    name = "python_src",
+    build_setting_default = "//python:none",
+)

python/private/interpreter.bzl

@@ -0,0 +1,71 @@
+# 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.
+
+"""Implementation of the rules to access the underlying Python interpreter."""
+
+load("@bazel_skylib//lib:paths.bzl", "paths")
+load("//python:py_runtime_info.bzl", "PyRuntimeInfo")
+load(":sentinel.bzl", "SentinelInfo")
+load(":toolchain_types.bzl", "TARGET_TOOLCHAIN_TYPE")
+
+def _interpreter_binary_impl(ctx):
+    if SentinelInfo in ctx.attr.binary:
+        toolchain = ctx.toolchains[TARGET_TOOLCHAIN_TYPE]
+        runtime = toolchain.py3_runtime
+    else:
+        runtime = ctx.attr.binary[PyRuntimeInfo]
+
+    # NOTE: We name the output filename after the underlying file name
+    # because of things like pyenv: they use $0 to determine what to
+    # re-exec. If it's not a recognized name, then they fail.
+    if runtime.interpreter:
+        executable = ctx.actions.declare_file(runtime.interpreter.basename)
+        ctx.actions.expand_template(
+            template = ctx.file._template,
+            output = executable,
+            substitutions = {
+                "%target_file%": runtime.interpreter.short_path,
+            },
+            is_executable = True,
+        )
+    else:
+        executable = ctx.actions.declare_symlink(paths.basename(runtime.interpreter_path))
+        ctx.actions.symlink(output = executable, target_path = runtime.interpreter_path)
+
+    return [
+        DefaultInfo(
+            executable = executable,
+            runfiles = ctx.runfiles([executable], transitive_files = runtime.files).merge_all([
+                ctx.attr._bash_runfiles[DefaultInfo].default_runfiles,
+            ]),
+        ),
+    ]
+
+interpreter_binary = rule(
+    implementation = _interpreter_binary_impl,
+    toolchains = [TARGET_TOOLCHAIN_TYPE],
+    executable = True,
+    attrs = {
+        "binary": attr.label(
+            mandatory = True,
+        ),
+        "_bash_runfiles": attr.label(
+            default = "@bazel_tools//tools/bash/runfiles",
+        ),
+        "_template": attr.label(
+            default = "//python/private:interpreter_tmpl.sh",
+            allow_single_file = True,
+        ),
+    },
+)

python/private/interpreter_tmpl.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+# --- begin runfiles.bash initialization v3 ---
+# Copy-pasted from the Bazel Bash runfiles library v3.
+set -uo pipefail; set +e; f=bazel_tools/tools/bash/runfiles/runfiles.bash
+# shellcheck disable=SC1090
+source "${RUNFILES_DIR:-/dev/null}/$f" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " "${RUNFILES_MANIFEST_FILE:-/dev/null}" | cut -f2- -d' ')" 2>/dev/null || \
+  source "$0.runfiles/$f" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " "$0.runfiles_manifest" | cut -f2- -d' ')" 2>/dev/null || \
+  source "$(grep -sm1 "^$f " "$0.exe.runfiles_manifest" | cut -f2- -d' ')" 2>/dev/null || \
+  { echo>&2 "ERROR: cannot find $f"; exit 1; }; f=; set -e
+# --- end runfiles.bash initialization v3 ---
+
+readonly TARGET_FILE="%target_file%"
+
+MAIN_BIN="$(rlocation "${TARGET_FILE#*/}")"
+
+exec "${MAIN_BIN}" "$@"

python/private/site_init_template.py

@@ -163,7 +163,9 @@ def _maybe_add_path(path):
         if cov_tool:
             _print_verbose_coverage(f"Using toolchain coverage_tool {cov_tool}")
         elif cov_tool := os.environ.get("PYTHON_COVERAGE"):
-            _print_verbose_coverage(f"Using env var coverage: PYTHON_COVERAGE={cov_tool}")
+            _print_verbose_coverage(
+                f"Using env var coverage: PYTHON_COVERAGE={cov_tool}"
+            )
 
         if cov_tool:
             if os.path.isabs(cov_tool):

python/private/stage2_bootstrap_template.py

@@ -398,6 +398,7 @@ def main():
 
     if os.environ.get("COVERAGE_DIR"):
         import _bazel_site_init
+
         coverage_enabled = _bazel_site_init.COVERAGE_SETUP
     else:
         coverage_enabled = False

tests/interpreter/BUILD.bazel

@@ -0,0 +1,58 @@
+# Copyright 2024 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("//tests/support:sh_py_run_test.bzl", "py_reconfig_test")
+
+PYTHON_VERSIONS_TO_TEST = (
+    "3.10",
+    "3.11",
+    "3.12",
+)
+
+[py_reconfig_test(
+    name = "python_version_%s_test" % python_version,
+    srcs = ["interpreter_test.py"],
+    data = [
+        "//python/bin:python",
+    ],
+    env = {
+        # Both the interpreter and the test itself are expected to run under
+        # the same version.
+        "EXPECTED_INTERPRETER_VERSION": python_version,
+        "EXPECTED_SELF_VERSION": python_version,
+        "PYTHON_BIN": "$(rootpath //python/bin:python)",
+    },
+    main = "interpreter_test.py",
+    python_version = python_version,
+) for python_version in PYTHON_VERSIONS_TO_TEST]
+
+[py_reconfig_test(
+    name = "python_src_%s_test" % python_version,
+    srcs = ["interpreter_test.py"],
+    data = [
+        "//python/bin:python",
+    ],
+    env = {
+        # Since we're grabbing the interpreter from a binary with a fixed
+        # version, we expect to always see that version. It doesn't matter what
+        # Python version the test itself is running with.
+        "EXPECTED_INTERPRETER_VERSION": "3.11",
+        # The test itself is still running under different Python versions.
+        "EXPECTED_SELF_VERSION": python_version,
+        "PYTHON_BIN": "$(rootpath //python/bin:python)",
+    },
+    main = "interpreter_test.py",
+    python_src = "//tools/publish:twine",
+    python_version = python_version,
+) for python_version in PYTHON_VERSIONS_TO_TEST]

tests/interpreter/interpreter_test.py

@@ -0,0 +1,78 @@
+# Copyright 2024 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.
+
+import os
+import subprocess
+import sys
+import unittest
+
+
+class InterpreterTest(unittest.TestCase):
+    def setUp(self):
+        super().setUp()
+        self.interpreter = os.environ["PYTHON_BIN"]
+
+    def test_self_version(self):
+        """Performs a sanity check on the Python version used for this test."""
+        expected_version = os.environ["EXPECTED_SELF_VERSION"]
+        v = sys.version_info
+        self.assertEqual(expected_version, f"{v.major}.{v.minor}")
+
+    def test_interpreter_version(self):
+        """Validates that we can successfully execute arbitrary code from the CLI."""
+        expected_version = os.environ["EXPECTED_INTERPRETER_VERSION"]
+
+        try:
+            result = subprocess.check_output(
+                [self.interpreter],
+                text=True,
+                stderr=subprocess.STDOUT,
+                input="\r".join(
+                    [
+                        "import sys",
+                        "v = sys.version_info",
+                        "print(f'version: {v.major}.{v.minor}')",
+                    ]
+                ),
+            ).strip()
+        except subprocess.CalledProcessError as error:
+            print("OUTPUT:", error.stdout)
+            raise
+
+        self.assertEqual(result, f"version: {expected_version}")
+
+    def test_json_tool(self):
+        """Validates that we can successfully invoke a module from the CLI."""
+        # Pass unformatted JSON to the json.tool module.
+        try:
+            result = subprocess.check_output(
+                [
+                    self.interpreter,
+                    "-m",
+                    "json.tool",
+                ],
+                text=True,
+                stderr=subprocess.STDOUT,
+                input='{"json":"obj"}',
+            ).strip()
+        except subprocess.CalledProcessError as error:
+            print("OUTPUT:", error.stdout)
+            raise
+
+        # Validate that we get formatted JSON back.
+        self.assertEqual(result, '{\n    "json": "obj"\n}')
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/support/sh_py_run_test.bzl

@@ -33,6 +33,8 @@ def _perform_transition_impl(input_settings, attr):
         settings["//command_line_option:extra_toolchains"] = attr.extra_toolchains
     if attr.python_version:
         settings["//python/config_settings:python_version"] = attr.python_version
+    if attr.python_src:
+        settings["//python/bin:python_src"] = attr.python_src
     if attr.venvs_use_declare_symlink:
         settings["//python/config_settings:venvs_use_declare_symlink"] = attr.venvs_use_declare_symlink
     return settings
@@ -43,13 +45,15 @@ _perform_transition = transition(
         "//python/config_settings:bootstrap_impl",
         "//command_line_option:extra_toolchains",
         "//python/config_settings:python_version",
+        "//python/bin:python_src",
         "//python/config_settings:venvs_use_declare_symlink",
     ],
     outputs = [
         "//command_line_option:build_python_zip",
         "//command_line_option:extra_toolchains",
         "//python/config_settings:bootstrap_impl",
         "//python/config_settings:python_version",
+        "//python/bin:python_src",
         "//python/config_settings:venvs_use_declare_symlink",
         VISIBLE_FOR_TESTING,
     ],
@@ -108,6 +112,7 @@ to make the RBE presubmits happy, which disable auto-detection of a CC
 toolchain.
 """,
         ),
+        "python_src": attr.label(),
         "python_version": attr.string(),
         "target": attr.label(executable = True, cfg = "target"),
         "venvs_use_declare_symlink": attr.string(),
@@ -133,6 +138,7 @@ def _py_reconfig_executable(*, name, py_reconfig_rule, py_inner_rule, **kwargs):
         "build_python_zip",
         "extra_toolchains",
         "python_version",
+        "python_src",
         "venvs_use_declare_symlink",
     ]
     reconfig_kwargs = {