use full runfiles path; add basic docs

Author: rickeylev

docs/api/rules_python/python/bin/index.md

@@ -0,0 +1,41 @@
+:::{default-domain} bzl
+:::
+:::{bzl:currentfile} //python/bin:BUILD.bazel
+:::
+
+# //python/bin
+
+:::{bzl:target} python
+
+A target to directly run a Python interpreter.
+
+By default, it uses the Python version that toolchain resolution matches
+(typically the one marked `is_default=True` in `MODULE.bazel`).
+
+This runs a Python interpreter in a similar manner as when running `python3`
+on the command line. It can be invoked using `bazel run`. Remember that in
+order to pass flags onto the program `--` must be specified to separate
+Bazel flags from the program flags.
+
+An example that will run Python 3.12 and have it print the version
+
+```
+bazel run @rules_python//python/bin:python \
+  `--@rule_python//python/config_settings:python_verion=3.12 \
+  -- \
+  --version
+```
+
+::::{seealso}
+The {flag}`--python_src` flag for using the intepreter a binary/test uses.
+::::
+
+::::{versionadded} VERSION_NEXT_FEATURE
+::::
+:::
+
+:::{bzl:flag} python_src
+
+The target (one providing `PyRuntimeInfo`) whose python interpreter to use for
+{obj}`:python`.
+:::

python/private/common.bzl

@@ -543,3 +543,20 @@ def target_platform_has_any_constraint(ctx, constraints):
         if ctx.target_platform_has_constraint(constraint_value):
             return True
     return False
+
+def runfiles_root_path(ctx, short_path):
+    """Compute a runfiles-root relative path from `File.short_path`
+
+    Args:
+        ctx: current target ctx
+        short_path: str, a main-repo relative path from `File.short_path`
+
+    Returns:
+        {type}`str`, a runflies-root relative path
+    """
+
+    # The ../ comes from short_path is for files in other repos.
+    if short_path.startswith("../"):
+        return short_path[3:]
+    else:
+        return "{}/{}".format(ctx.workspace_name, short_path)

python/private/interpreter.bzl

@@ -16,6 +16,7 @@
 
 load("@bazel_skylib//lib:paths.bzl", "paths")
 load("//python:py_runtime_info.bzl", "PyRuntimeInfo")
+load(":common.bzl", "runfiles_root_path")
 load(":sentinel.bzl", "SentinelInfo")
 load(":toolchain_types.bzl", "TARGET_TOOLCHAIN_TYPE")
 
@@ -45,10 +46,7 @@ def _interpreter_binary_impl(ctx):
             template = ctx.file._template,
             output = executable,
             substitutions = {
-                # Since we never invoke this rule from within the interpreter's
-                # own repository, the short_path here should give us a
-                # predictable path of "../<repo>/<path within repo>".
-                "%target_file%": runtime.interpreter.short_path,
+                "%target_file%": runfiles_root_path(ctx, runtime.interpreter.short_path),
             },
             is_executable = True,
         )

python/private/interpreter_tmpl.sh

@@ -12,10 +12,12 @@ source "${RUNFILES_DIR:-/dev/null}/$f" 2>/dev/null || \
   { echo>&2 "ERROR: cannot find $f"; exit 1; }; f=; set -e
 # --- end runfiles.bash initialization v3 ---
 
+set +e # allow us to check for errors more easily
 readonly TARGET_FILE="%target_file%"
+MAIN_BIN=$(rlocation "$TARGET_FILE")
 
-# Strip the leading "../" from "../<repo>/<path within repo>" so that we can do
-# a runfiles lookup.
-MAIN_BIN="$(rlocation "${TARGET_FILE#*/}")"
-
+if [[ -z "$MAIN_BIN" || ! -e "$MAIN_BIN" ]]; then
+  echo "ERROR: interpreter executable not found: $MAIN_BIN (from $TARGET_FILE)"
+  exit 1
+fi
 exec "${MAIN_BIN}" "$@"

python/private/py_executable.bzl

@@ -48,6 +48,7 @@ load(
     "filter_to_py_srcs",
     "get_imports",
     "is_bool",
+    "runfiles_root_path",
     "target_platform_has_any_constraint",
     "union_attrs",
 )
@@ -447,7 +448,7 @@ def _create_executable(
     )
 
 def _create_zip_main(ctx, *, stage2_bootstrap, runtime_details, venv):
-    python_binary = _runfiles_root_path(ctx, venv.interpreter.short_path)
+    python_binary = runfiles_root_path(ctx, venv.interpreter.short_path)
     python_binary_actual = venv.interpreter_actual_path
 
     # The location of this file doesn't really matter. It's added to
@@ -522,7 +523,7 @@ def _create_venv(ctx, output_prefix, imports, runtime_details):
 
     if not venvs_use_declare_symlink_enabled:
         if runtime.interpreter:
-            interpreter_actual_path = _runfiles_root_path(ctx, runtime.interpreter.short_path)
+            interpreter_actual_path = runfiles_root_path(ctx, runtime.interpreter.short_path)
         else:
             interpreter_actual_path = runtime.interpreter_path
 
@@ -543,11 +544,11 @@ def _create_venv(ctx, output_prefix, imports, runtime_details):
         # may choose to write what symlink() points to instead.
         interpreter = ctx.actions.declare_symlink("{}/bin/{}".format(venv, py_exe_basename))
 
-        interpreter_actual_path = _runfiles_root_path(ctx, runtime.interpreter.short_path)
+        interpreter_actual_path = runfiles_root_path(ctx, runtime.interpreter.short_path)
         rel_path = relative_path(
             # dirname is necessary because a relative symlink is relative to
             # the directory the symlink resides within.
-            from_ = paths.dirname(_runfiles_root_path(ctx, interpreter.short_path)),
+            from_ = paths.dirname(runfiles_root_path(ctx, interpreter.short_path)),
             to = interpreter_actual_path,
         )
 
@@ -646,23 +647,6 @@ def _create_stage2_bootstrap(
     )
     return output
 
-def _runfiles_root_path(ctx, short_path):
-    """Compute a runfiles-root relative path from `File.short_path`
-
-    Args:
-        ctx: current target ctx
-        short_path: str, a main-repo relative path from `File.short_path`
-
-    Returns:
-        {type}`str`, a runflies-root relative path
-    """
-
-    # The ../ comes from short_path is for files in other repos.
-    if short_path.startswith("../"):
-        return short_path[3:]
-    else:
-        return "{}/{}".format(ctx.workspace_name, short_path)
-
 def _create_stage1_bootstrap(
         ctx,
         *,
@@ -676,7 +660,7 @@ def _create_stage1_bootstrap(
     runtime = runtime_details.effective_runtime
 
     if venv:
-        python_binary_path = _runfiles_root_path(ctx, venv.interpreter.short_path)
+        python_binary_path = runfiles_root_path(ctx, venv.interpreter.short_path)
     else:
         python_binary_path = runtime_details.executable_interpreter_path