feat: env-var for additional interpreter args in bootstrap stage 1 (#2654)

There is no means to be able to provide additional interpreter arguments
to the `bash`-based stage 1 bootstrap system at launch time.

The Intelli-J / Bazel plugin typically launches a `py_*` rule build
product with something like this (abridged) using a Python interpreter
from the local environment;

```
python3 /path/to/pydev/pydevd.py --client 127.0.0.1 --port 12344 --file /path/to/built/python-file
```

When the `bash`-based bootstrap process is used, this mechanism not
longer works. This PR will mean that a potential future Intelli-j /
Bazel plugin version may be able to launch the build product differently
and inject additional interpreter arguments so that the debug system can
be stood up in this sort of a way;

```
RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS="/path/to/pydev/pydevd.py --client 127.0.0.1 --port 12344 --file" /path/to/bash-bootstrap-stage1-script
```

The work to support this in the Intelli-J / Bazel plugin has not been
done; it would have to be undertaken some time after this change were
available.

---------

Co-authored-by: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
Co-authored-by: Richard Levasseur <rlevasseur@google.com>

CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc24193..15fb211 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -94,6 +94,9 @@
 * (rules) APIs for creating custom rules based on the core py_binary, py_test,
   and py_library rules
   ([#1647](https://github.com/bazelbuild/rules_python/issues/1647))
+* (rules) Added env-var to allow additional interpreter args for stage1 bootstrap.
+  See {obj}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable.
+  Only applicable for {obj}`--bootstrap_impl=script`.
 * (rules) Added {obj}`interpreter_args` attribute to `py_binary` and `py_test`,
   which allows pass arguments to the interpreter before the regular args.
 

docs/environment-variables.md

diff --git a/docs/environment-variables.md b/docs/environment-variables.md
index d50070a..c7c0181 100644
--- a/docs/environment-variables.md
+++ b/docs/environment-variables.md
@@ -1,5 +1,33 @@
 # Environment Variables
 
+::::{envvar} RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS
+
+This variable allows for additional arguments to be provided to the Python interpreter
+at bootstrap time when the `bash` bootstrap is used. If
+`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` were provided as `-Xaaa`, then the command
+would be;
+
+```
+python -Xaaa /path/to/file.py
+```
+
+This feature is likely to be useful for the integration of debuggers. For example,
+it would be possible to configure the `RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` to
+be set to `/path/to/debugger.py --port 12344 --file` resulting
+in the command executed being;
+
+```
+python /path/to/debugger.py --port 12345 --file /path/to/file.py
+```
+
+:::{seealso}
+The {bzl:obj}`interpreter_args` attribute.
+:::
+
+:::{versionadded} VERSION_NEXT_FEATURE
+
+::::
+
 :::{envvar} RULES_PYTHON_BOOTSTRAP_VERBOSE
 
 When `1`, debug information about bootstrapping of a program is printed to

python/private/py_executable.bzl

diff --git a/python/private/py_executable.bzl b/python/private/py_executable.bzl
index d190544..bbaed31 100644
--- a/python/private/py_executable.bzl
+++ b/python/private/py_executable.bzl
@@ -98,6 +98,10 @@
 Only supported for {obj}`--bootstrap_impl=script`. Ignored otherwise.
 :::
 
+:::{seealso}
+The {obj}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable
+:::
+
 :::{versionadded} VERSION_NEXT_FEATURE
 :::
 """,

python/private/stage1_bootstrap_template.sh

diff --git a/python/private/stage1_bootstrap_template.sh b/python/private/stage1_bootstrap_template.sh
index 523210a..bd142cf 100644
--- a/python/private/stage1_bootstrap_template.sh
+++ b/python/private/stage1_bootstrap_template.sh
@@ -202,6 +202,7 @@
 
 declare -a interpreter_env
 declare -a interpreter_args
+declare -a additional_interpreter_args
 
 # Don't prepend a potentially unsafe path to sys.path
 # See: https://docs.python.org/3.11/using/cmdline.html#envvar-PYTHONSAFEPATH
@@ -220,6 +221,12 @@
   interpreter_args+=("-XRULES_PYTHON_ZIP_DIR=$zip_dir")
 fi
 
+if [[ -n "${RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS}" ]]; then
+  read -a additional_interpreter_args <<< "${RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS}"
+  interpreter_args+=("${additional_interpreter_args[@]}")
+  unset RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS
+fi
+
 export RUNFILES_DIR
 
 command=(