Support debugging Python web applications (#4924)

This PR adds "Debug \<Framework\> App in Terminal" commands for all of
the currently supported Python app frameworks.

There was a fair bit of moving things around to reuse code between the
run and debug commands.

Addresses #4795.

### QA Notes

Test the commands for each app framework, see the examples for each
framework in #4662.

extensions/positron-python/package.json

@@ -348,6 +348,48 @@
                 "icon": "$(play)",
                 "title": "%python.command.python.execInConsole.title%"
             },
+            {
+                "category": "Python",
+                "command": "python.debugDashInTerminal",
+                "icon": "$(debug-alt)",
+                "title": "%python.command.python.debugDashInTerminal.title%",
+                "enablement": "pythonAppFramework == dash"
+            },
+            {
+                "category": "Python",
+                "command": "python.debugFastAPIInTerminal",
+                "icon": "$(debug-alt)",
+                "title": "%python.command.python.debugFastAPIInTerminal.title%",
+                "enablement": "pythonAppFramework == fastapi"
+            },
+            {
+                "category": "Python",
+                "command": "python.debugFlaskInTerminal",
+                "icon": "$(debug-alt)",
+                "title": "%python.command.python.debugFlaskInTerminal.title%",
+                "enablement": "pythonAppFramework == flask"
+            },
+            {
+                "category": "Python",
+                "command": "python.debugGradioInTerminal",
+                "icon": "$(debug-alt)",
+                "title": "%python.command.python.debugGradioInTerminal.title%",
+                "enablement": "pythonAppFramework == gradio"
+            },
+            {
+                "category": "Python",
+                "command": "python.debugShinyInTerminal",
+                "icon": "$(debug-alt)",
+                "title": "%python.command.python.debugShinyInTerminal.title%",
+                "enablement": "pythonAppFramework == shiny"
+            },
+            {
+                "category": "Python",
+                "command": "python.debugStreamlitInTerminal",
+                "icon": "$(debug-alt)",
+                "title": "%python.command.python.debugStreamlitInTerminal.title%",
+                "enablement": "pythonAppFramework == streamlit"
+            },
             {
                 "category": "Python",
                 "command": "python.debugInTerminal",
@@ -1600,8 +1642,44 @@
                     "when": "resourceLangId == python && !isInDiffEditor && !virtualWorkspace && shellExecutionSupported"
                 },
                 {
-                    "command": "python.debugInTerminal",
+                    "command": "python.debugDashInTerminal",
+                    "group": "navigation@3",
+                    "title": "%python.command.python.debugDashInTerminal.title%",
+                    "when": "pythonAppFramework == dash"
+                },
+                {
+                    "command": "python.debugGradioInTerminal",
                     "group": "navigation@3",
+                    "title": "%python.command.python.debugGradioInTerminal.title%",
+                    "when": "pythonAppFramework == gradio"
+                },
+                {
+                    "command": "python.debugShinyInTerminal",
+                    "group": "navigation@3",
+                    "title": "%python.command.python.debugShinyInTerminal.title%",
+                    "when": "pythonAppFramework == shiny"
+                },
+                {
+                    "command": "python.debugFastAPIInTerminal",
+                    "group": "navigation@3",
+                    "title": "%python.command.python.debugFastAPIInTerminal.title%",
+                    "when": "pythonAppFramework == fastapi"
+                },
+                {
+                    "command": "python.debugFlaskInTerminal",
+                    "group": "navigation@3",
+                    "title": "%python.command.python.debugFlaskInTerminal.title%",
+                    "when": "pythonAppFramework == flask"
+                },
+                {
+                    "command": "python.debugStreamlitInTerminal",
+                    "group": "navigation@3",
+                    "title": "%python.command.python.debugStreamlitInTerminal.title%",
+                    "when": "pythonAppFramework == streamlit"
+                },
+                {
+                    "command": "python.debugInTerminal",
+                    "group": "navigation@4",
                     "title": "%python.command.python.debugInTerminal.title%",
                     "when": "resourceLangId == python && !isInDiffEditor && !virtualWorkspace && shellExecutionSupported"
                 }

extensions/positron-python/package.nls.json

@@ -10,8 +10,14 @@
     "python.command.python.execFastAPIInTerminal.title": "Run FastAPI App in Terminal",
     "python.command.python.execFlaskInTerminal.title": "Run Flask App in Terminal",
     "python.command.python.execGradioInTerminal.title": "Run Gradio App in Terminal",
-    "python.command.python.execShinyInTerminal.title": "Run Shiny App in Terminal", 
+    "python.command.python.execShinyInTerminal.title": "Run Shiny App in Terminal",
     "python.command.python.execStreamlitInTerminal.title": "Run Streamlit App in Terminal",
+    "python.command.python.debugDashInTerminal.title": "Debug Dash App in Terminal",
+    "python.command.python.debugFastAPIInTerminal.title": "Debug FastAPI App in Terminal",
+    "python.command.python.debugFlaskInTerminal.title": "Debug Flask App in Terminal",
+    "python.command.python.debugGradioInTerminal.title": "Debug Gradio App in Terminal",
+    "python.command.python.debugShinyInTerminal.title": "Debug Shiny App in Terminal",
+    "python.command.python.debugStreamlitInTerminal.title": "Debug Streamlit App in Terminal",
     "python.command.python.execInConsole.title": "Run Python File in Console",
     "python.command.python.debugInTerminal.title": "Debug Python File in Terminal",
     "python.command.python.execInTerminalIcon.title": "Run Python File in Terminal",

extensions/positron-python/src/client/common/constants.ts

@@ -60,6 +60,12 @@ export namespace Commands {
     export const Exec_Streamlit_In_Terminal = 'python.execStreamlitInTerminal';
     export const Exec_In_Console = 'python.execInConsole';
     export const Exec_Selection_In_Console = 'python.execSelectionInConsole';
+    export const Debug_Dash_In_Terminal = 'python.debugDashInTerminal';
+    export const Debug_FastAPI_In_Terminal = 'python.debugFastAPIInTerminal';
+    export const Debug_Flask_In_Terminal = 'python.debugFlaskInTerminal';
+    export const Debug_Gradio_In_Terminal = 'python.debugGradioInTerminal';
+    export const Debug_Shiny_In_Terminal = 'python.debugShinyInTerminal';
+    export const Debug_Streamlit_In_Terminal = 'python.debugStreamlitInTerminal';
     // --- End Positron ---
     export const Exec_In_REPL = 'python.execInREPL';
     export const Exec_Selection_In_Django_Shell = 'python.execSelectionInDjangoShell';

extensions/positron-python/src/client/positron-run-app.d.ts

@@ -53,6 +53,39 @@ export interface RunAppOptions {
     urlPath?: string;
 }
 
+/**
+ * Represents options for the ${@link PositronRunApp.debugApplication} function.
+ */
+export interface DebugAppOptions {
+    /**
+     * The human-readable label for the application e.g. `'Shiny'`.
+     */
+    name: string;
+
+    /**
+     * A function that will be called to get the ${@link vscode.DebugConfiguration, debug configuration} for debugging the application.
+     *
+     * @param runtime The language runtime metadata for the document's language.
+     * @param document The document to debug.
+     * @param port The port to run the application on, if known.
+     * @param urlPrefix The URL prefix to use, if known.
+     * @returns The debug configuration for debugging the application. Return `undefined` to abort debugging.
+     */
+    getDebugConfiguration(
+        runtime: positron.LanguageRuntimeMetadata,
+        document: vscode.TextDocument,
+        port?: string,
+        urlPrefix?: string,
+    ): vscode.DebugConfiguration | undefined | Promise<vscode.DebugConfiguration | undefined>;
+
+    /**
+     * The optional URL path at which to preview the application.
+     */
+    urlPath?: string;
+}
+
+export interface DebugConfiguration {}
+
 /**
  * The public API of the Positron Run App extension.
  */
@@ -65,4 +98,13 @@ export interface PositronRunApp {
      *  started, otherwise resolves when the command has been sent to the terminal.
      */
     runApplication(options: RunAppOptions): Promise<void>;
+
+    /**
+     * Debug an application.
+     *
+     * @param options Options for debugging the application.
+     * @returns If terminal shell integration is supported, resolves when the application server has
+     *  started, otherwise resolves when the debug session has started.
+     */
+    debugApplication(options: DebugAppOptions): Promise<void>;
 }