Example in local environment doc page causes hard-to-debug errors

[wch]

Bug description

On this page: https://quarto.org/docs/projects/environment.html#local-environment

It provides an example of _environment.local where it sets the following variables:

PYTHONINSPECT=1
PYTHONDEVMODE=1

However, setting PYTHONINSPECT=1 will cause Python to behave in a way that I think will always cause hard-to-debug errors when running a Lua filter that calls out to Python. From the documentation:

PYTHONINSPECT
If this is set to a non-empty string it is equivalent to specifying the -i option.

And for -i:

-i
When a script is passed as first argument or the -c option is used, enter interactive mode after executing the script or the command, even when sys.stdin does not appear to be a terminal.

So this will cause Python to always go to a terminal after executing the Python code, and that will in turn cause hard-to-debug errors when run from Quarto. Note that this error happens when using a Lua filter which calls a Python script, but it does not happen when running a {python} code block in the qmd file.

In my particular case, I am calling a Python script from the shinylive Lua filter. See quarto-ext/shinylive#17

For the {python} code block case, setting PYTHONINSPECT=1 doesn't seem to cause an error. However, it also doesn't seem to be helpful for debugging because it doesn't actually put you in an interactive terminal when Python is run from Quarto. So using that specific variable in the example page seems to only cause problems.

Steps to reproduce

To reproduce:

• Create a Quarto project and use a Lua filter (like shinylive) which calls a Python script
• Run quarto render foo.qmd

Expected behavior

The page should build without error.

Actual behavior

In my case, I got errors like this:

Traceback (most recent call last):
  File "/Users/winston/nobackup/dropbox-nosync/shinylive/venv/lib/python3.11/site-packages/click/core.py", line 1088, in main
    ctx.exit()
  File "/Users/winston/nobackup/dropbox-nosync/shinylive/venv/lib/python3.11/site-packages/click/core.py", line 692, in exit
    raise Exit(code)
click.exceptions.Exit: 0

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/winston/nobackup/dropbox-nosync/shinylive/venv/bin/shinylive", line 39, in <module>
    sys.exit(load_entry_point('shinylive', 'console_scripts', 'shinylive')())
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/winston/nobackup/dropbox-nosync/shinylive/venv/lib/python3.11/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/winston/nobackup/dropbox-nosync/shinylive/venv/lib/python3.11/site-packages/click/core.py", line 1106, in main
    sys.exit(e.exit_code)
SystemExit: 0
Error running filter /Users/winston/nobackup/quarto-cli/src/resources/filters/main.lua:
Error running shinylive (error code 1):

Your environment

• OS: MacOS Ventura 13.5 (22G74)

Quarto check output

I'm using the v1.3.450 commit of this repo.

$ quarto check

[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.1: OK
      Dart Sass version 1.55.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 99.9.9
      Path: /Users/winston/nobackup/quarto-cli/package/dist/bin

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.11.4
      Path: /Users/winston/nobackup/dropbox-nosync/shinylive/venv/bin/python3
      Jupyter: 5.3.0
      Kernels: python3

(-) Checking Jupyter engine render....0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
      Version: 4.3.0
      Path: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources
      LibPaths:
        - /Users/winston/R/4.3
        - /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/library
      knitr: 1.43
      rmarkdown: 2.23

[✓] Checking Knitr engine render......OK

[dragonstyle]

I removed this from the example.