feat: env-var for additional interpreter args in bootstrap stage 1

CHANGELOG.md

@@ -94,6 +94,7 @@ Unreleased changes template.
 * (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
 
 {#v0-0-0-removed}
 ### Removed

docs/environment-variables.md

@@ -1,5 +1,29 @@
 # 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
+```
+
+:::{versionadded} VERSION_NEXT_FEATURE
+
+::::
+
 :::{envvar} RULES_PYTHON_BOOTSTRAP_VERBOSE
 
 When `1`, debug information about bootstrapping of a program is printed to

python/private/stage1_bootstrap_template.sh

@@ -197,6 +197,7 @@ stage2_bootstrap="$RUNFILES_DIR/$STAGE2_BOOTSTRAP"
 
 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
@@ -215,6 +216,12 @@ if [[ "$IS_ZIPFILE" == "1" ]]; then
   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=(