deprecate --export-py-hermetic-scripts in favor of new --export-py-non-hermetic-scripts-in-resolve option

docs/notes/2.23.x.md

@@ -96,6 +96,8 @@ Exported virtualenvs can use Pants-provided Python if a `PythonProvider` backend
 
 The docs for the `check` goal have been updated to state that third-party type stubs must be installed in the same resolve as the code.
 
+Deprecate the `--export-py-hermetic-scripts` option in favor of the new `--export-py-non-hermetic-scripts-in-resolve` option which allows configuring the hermetic scripts logic on a per-resolve basis.
+
 #### Terraform
 
 The default version of terraform has been updated from 1.7.1 to 1.9.0.

src/python/pants/backend/python/goals/export.py

@@ -134,6 +134,37 @@ class ExportPluginOptions:
             """
         ),
         advanced=True,
+        removal_version="2.24.0.dev0",
+        removal_hint=softwrap(
+            """
+            Use `--export-py-non-hermetic-scripts-in-resolve` instead.
+            """
+        ),
+    )
+
+    py_non_hermetic_scripts_in_resolve = StrListOption(
+        help=softwrap(
+            """
+            When exporting a mutable virtualenv for a resolve listed in this option, by default
+            console script shebang lines will be made "hermetic". Specifically, the shebang of
+            hermetic console scripts will uses the python args `-sE` where:
+
+              - `-s` skips inclusion of the user site-packages directory,
+              - `-E` ignores all `PYTHON*` env vars like `PYTHONPATH`.
+
+            If you need "non-hermetic" scripts for a partcular resolve, then add that resolve's name
+            to this option. This will allow simple python shebangs that respect vars like
+            `PYTHONPATH`, which, for example, will allow IDEs like PyCharm to inject its debugger,
+            coverage, or other IDE-specific libs when running a script.
+
+            This only applies when when exporting a `mutable_virtualenv`
+            (`symlinked_immutable_virtualenv` exports are not "full"
+            virtualenvs because they are used internally by pants itself.
+            Pants requires hermetic scripts to provide its reproduciblity
+            guarantee, fine-grained caching, and other features).
+            """
+        ),
+        advanced=True,
     )
 
     py_generated_sources_in_resolve = StrListOption(
@@ -252,7 +283,10 @@ async def do_export(
             f"--prompt={venv_prompt}",
             output_path,
         ]
-        if not export_subsys.options.py_hermetic_scripts:
+        if (
+            req.resolve_name in export_subsys.options.py_non_hermetic_scripts_in_resolve
+            or not export_subsys.options.py_hermetic_scripts
+        ):
             pex_args.insert(-1, "--non-hermetic-scripts")
 
         post_processing_cmds = [

src/python/pants/backend/python/goals/export_integration_test.py

@@ -54,7 +54,7 @@ def build_config(
         },
         "export": {
             "py_resolve_format": py_resolve_format.value,
-            "py_hermetic_scripts": py_hermetic_scripts,
+            "py_non_hermetic_scripts_in_resolve": [] if py_hermetic_scripts else ["a", "b"],
         },
     }
 

src/python/pants/backend/python/goals/export_test.py

@@ -103,7 +103,9 @@ def test_export_venv_new_codepath(
     )
 
     format_flag = f"--export-py-resolve-format={py_resolve_format.value}"
-    hermetic_flags = [] if py_hermetic_scripts else ["--export-py-hermetic-scripts=false"]
+    hermetic_flags = (
+        [] if py_hermetic_scripts else ["--export-py-non-hermetic-scripts-in-resolve=['a', 'b']"]
+    )
     rule_runner.set_options(
         [
             *pants_args_for_python_lockfiles,