Debugging python functions in a Quarto doc

[boshek]

Description

I am wondering how folks have approach interactively debugging python functions in a Quarto doc that is not just using print. Right now I am using something that mimics R's browser functionality. The workflow I use in R is something like this:

---
format: html
---


```{r}
add_one <- function(x) {
    browser()
    x + 1
}

add_one(1)
```

if I wanted to step into the add_one function. This works great. So I wanted to replicate this workflow in python. Right now here is what I have using pdb:

---
format: html
---

```{python}
def add_one(x):
    import pdb; pdb.set_trace()
    return x + 1


add_one(1)
```

This works ok but it doesn't really take advantage of any of the nice IDE features of something like positron or vscode. Those tools are well setup for debugging python scripts but so far I don't think they really will drop you into a python function at a breakpoint from a quarto doc. Can anyone recommend any other strategies when using python in quarto docs particularly something that leverages the vscode/positron debugger?

[cscheid]

We're pretty far away from being able to do that. In any case, it's a feature request for http://github.com/quarto-dev/quarto (where we host the vscode/positron/rstudio integration code)

[boshek]

Ok thanks. I just wanted to make sure I wasn't missing anything. I can imagine what a big job it is for something like that.

Just to clarify would you like me to open this as a feature request?

[cscheid]

If you search around you'll find a few already.

[githubpsyche]

Using debugpy it's possible to debug a QMD file in a way that connects to VSCode or Positron's visual debugger.

Documentation for this feature is here:

https://code.visualstudio.com/docs/python/debugging#_debugging-by-attaching-over-a-network-connection

[mcanouil]

Thanks for sharing.

Could you properly format your post using code blocks for code and terminal outputs? Thanks.
If your code contains code blocks, you need to enclose it using more backticks, i.e., usually four ````.
See https://quarto.org/bug-reports.html#formatting-make-githubs-markdown-work-for-us.

[githubpsyche]

I'll write up a full example here. This is based on my comments in this issue quarto-dev/quarto#38 (comment) and the documentation here: https://code.visualstudio.com/docs/python/debugging#_local-script-debugging

You add a remote attach configuration to your .launch.json. However, it's not usually necessary to make this configuration yourself; VSCode helps set this up with an "Add Configuration" button at bottom left of the file opened into the editor. Treat this as an example:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Debugger: Remote Attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "."
                }
            ]
        }
    ]
}

And here's an example of a QMD document that connects to VSCode's Debugger UI:

---
title: "Quarto Basics"
format:
  html:
    code-fold: true
jupyter: python3
---

For a demonstration of a line plot on a polar axis, see @fig-polar.

```{python}
#| code-summary: code to start the debugger; attach to it in VS Code "Run and Debug" panel
import debugpy
debugpy.listen(5678)
debugpy.wait_for_client()
```

```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
breakpoint() # minimum needed to connect to VSCode's debugger UI at this point
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

The import debugpy; debugpy.listen(5678); debugpy.wait_for_client() stuff in the first cell only runs once and sets up the connection with VSCode's debugger interface. In the Run extension, you select your "Remote Attach" configuration and press the play button to attach. As long as you keep the debugpy.wait_for_client() example, the cell won't stop finish running until you finish the "Remote Attach".

From there, you can place debugpy.breakpoint() anywhere in your notebook to start a debugging session at that part of your code. You can even re-use debugpy.breakpoint() at multiple parts of your notebook and indeed seem to get access to variables created in other cells. Debugging console works, variable viewer works, and so on!

Furthermore, you can set breakpoints in external Python scripts used by your notebook in the "normal way" -- by clicking to add a red dot at the line where you want a breakpoint. When your QMD cell attempts to execute that line, the debugger is initialized correctly.

Finally, if you configure your debugger settings accordingly, Uncaught and User Uncaught Exceptions can trigger a debugging session without having to set any breakpoints.

So the only stuff lost with this approach is that you can't click to set breakpoints inside your QMD file and you have to do a bit more to set up and attach to the debugging session. UI-configured breakpoints in imported python scripts DO work, though, and you even get access to UI-configured breakpoints in code cells where you've triggered a breakpoint with debugpy.breakpoint().

[githubpsyche]

I have the feeling that this process could be streamlined in an eventual update to either Quarto or VSCode (or Positron). Maybe something that configures the remote connection automatically when a QMD code cell is first executed? It would also be a big quality of life improvement if there were simply a way to have the Remote Attach operation happen automatically when the first code cell is executed instead of having to perform that step manually each time...

From there, the only gap is that you can't toggle breakpoints using VSCode/Positron's UI. You still have to add a line to your script that executes breakpoint().

[mcanouil]

I have the feeling that this process could be streamlined in an eventual update to either Quarto or VSCode

Not Quarto CLI, but the extension for VSCode probably (https://github.com/quarto-dev/quarto).

[githubpsyche]

I'm interested in further brainstorming ways to streamline this without updates to software. It's possible that VSCode/Positron provides the tools but they're just tricky to navigate. Maybe after that I might propose including some details about this in the the VSCode/Positron-specific QMD documentation.

---

In increasing order of priority/onerousness:

Things that only have to be done once per project:

• Setup launch.json for Remote Debugger.

Things that have to be done once per QMD file:

• Manually add import debugpy; debugpy.listen(5678); debugpy.wait_for_client() for scripts that will use the debugger.
• Manually add calls to breakpoint() where breakpoints are desired.

Things that have to be done every time you start a fresh interactive session:

• Manually attach VSCode's Debugger to session after executing code cell calling debugpy.listen.

---

My intuition is that software will have to be updated to avoid the need for breakpoint() lines in QMD code cells. This issue can be sidestepped so much by keeping code you want to debug in an external script and calling it from the QMD code cell. VSCode/Positron's breakpoint UI works fine in this context.

However, it may be possible to configure -- at the project level -- the debugpy setup and IDE attachment to be performed automatically every time an interactive session begins. Maybe in the longterm this would be handled in quarto's vscode extension, but IPython itself provides an entry point for configuring what happens at kernel startup which might be easier to work with.

'Course even this is specific to Python....