docs (debugger): Update using debuggers how to guide on using debugpy (e.g. vscode) (#3547)

Thanks to help from @rickeylev in the discussion in
#3481 I was able to
do a debugger integration running bazel test or bazel run straight in
vscode (since it uses debugpy I suspect PyCharm should also work). Added
this workflow to the docs, hoping others might also find it useful.

Added page:
https://rules-python--3547.org.readthedocs.build/en/3547/howto/debuggers.html

Related to
#3485

---------

Co-authored-by: Shayan Hoshyari <hoshyari@adobe.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: 3 people

docs/environment-variables.md

@@ -11,7 +11,7 @@ would be:
 python -Xaaa /path/to/file.py
 ```
 
-This feature is likely to be useful for the integration of debuggers. For example,
+This feature is useful for the integration of debuggers. For example,
 it would be possible to configure `RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` to
 be set to `/path/to/debugger.py --port 12344 --file`, resulting
 in the command executed being:
@@ -22,6 +22,8 @@ python /path/to/debugger.py --port 12345 --file /path/to/file.py
 
 :::{seealso}
 The {bzl:obj}`interpreter_args` attribute.
+
+The guide on {any}`How to integrate a debugger`
 :::
 
 :::{versionadded} 1.3.0

docs/howto/debuggers.md

@@ -3,10 +3,14 @@
 
 # How to integrate a debugger
 
-This guide explains how to use the {obj}`--debugger` flag to integrate a debugger
+This guide explains how to integrate a debugger
 with your Python applications built with `rules_python`.
 
-## Basic Usage
+There are two ways available:  the {obj}`--debugger` flag, and the {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable.
+
+## {obj}`--debugger` flag
+
+### Basic Usage
 
 The {obj}`--debugger` flag allows you to inject an extra dependency into `py_test`
 and `py_binary` targets so that they have a custom debugger available at
@@ -32,7 +36,7 @@ The specified target must be in the requirements.txt file used with
 `pip.parse()` to make it available to Bazel.
 :::
 
-## Python `PYTHONBREAKPOINT` Environment Variable
+### Python `PYTHONBREAKPOINT` Environment Variable
 
 For more fine-grained control over debugging, especially for programmatic breakpoints,
 you can leverage the Python built-in `breakpoint()` function and the
@@ -52,7 +56,7 @@ PYTHONBREAKPOINT=pudb.set_trace bazel run \
 
 For more details on `PYTHONBREAKPOINT`, refer to the [Python documentation](https://docs.python.org/3/library/functions.html#breakpoint).
 
-## Setting a default debugger
+### Setting a default debugger
 
 By adding settings to your user or project `.bazelrc` files, you can have
 these settings automatically added to your bazel invocations. e.g.
@@ -64,3 +68,139 @@ common --test_env=PYTHONBREAKPOINT=pudb.set_trace
 
 Note that `--test_env` isn't strictly necessary. The `py_test` and `py_binary`
 rules will respect the `PYTHONBREAKPOINT` environment variable in your shell.
+
+## debugpy (e.g. vscode)
+
+You can integrate `debugpy` (i.e. the debugger used in vscode or PyCharm) by using a launcher script. This method leverages {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` to inject the debugger into the Bazel-managed Python process.
+
+For the remainder of this document, we assume you are using vscode.
+
+![VS Code debugpy demo](https://raw.githubusercontent.com/shayanhoshyari/issue-reports/refs/heads/main/rules_python/vscode_debugger/docs/demo.gif)
+
+
+1.  **Create a launcher script**: Save the following Python script as `.vscode/debugpy/launch.py` (or another location, adjusting `launch.json` accordingly). This script bridges VS Code's debugger with Bazel.
+
+    <details>
+    <summary><code>launch.py</code></summary>
+
+    ```python
+    """
+    Launcher script for VS Code (debugpy).
+
+    This script is not managed by Bazel; it is invoked by VS Code's launch.json to
+    wrap the Bazel command, injecting the debugger into the runtime environment.
+    """
+
+    import argparse
+    import os
+    import shlex
+    import subprocess
+    import sys
+    from typing import cast
+
+    def main() -> None:
+        parser = argparse.ArgumentParser(description="Launch bazel debugpy with test or run.")
+        parser.add_argument("mode", choices=["test", "run"], help="Choose whether to run a bazel test or run.")
+        parser.add_argument("args", help="The bazel target to test or run (e.g., //foo:bar) and any additional args")
+        args = parser.parse_args()
+
+        # Import debugpy, provided by VS Code
+        try:
+            # debugpy._vendored is needed for force_pydevd to perform path manipulation.
+            import debugpy._vendored  # type: ignore[import-not-found]
+
+            # pydev_monkey patches os and subprocess functions to handle new launched processes.
+            from _pydev_bundle import pydev_monkey  # type: ignore[import-not-found]
+        except ImportError as exc:
+            print(f"Error: This script must be run via VS Code's debug adapter. Details: {exc}")
+            sys.exit(-1)
+
+        # Prepare arguments for the monkey-patched process.
+        # is_exec=False ensures we don't replace the current process immediately.
+        patched_args = cast(list[str], pydev_monkey.patch_args(["python", "dummy.py"], is_exec=False))
+        pydev_monkey.send_process_created_message()
+
+        # Extract the injected arguments (skipping the dummy python executable and script).
+        # These args invoke the pydevd entrypoint which connects back to the debugger.
+        rules_python_interpreter_args = " ".join(patched_args[1:-1])
+
+        bzl_args = shlex.split(args.args)
+        if not bzl_args:
+            print("Error: At least one argument (the target) is required.")
+            sys.exit(-1)
+
+        cmd = [
+            "bazel",
+            args.mode,
+            # Propagate environment variables to the test/run environment.
+            "--test_env=PYDEVD_RESOLVE_SYMLINKS",
+            "--test_env=RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS",
+            "--test_env=IDE_PROJECT_ROOTS",
+            bzl_args[0],
+        ]
+
+        if bzl_args[1:]:
+            if args.mode == "run":
+                # Append extra arguments for 'run' mode.
+                cmd.append("--")
+                cmd.extend(bzl_args[1:])
+            elif args.mode == "test":
+                # Append extra arguments for 'test' mode.
+                cmd.extend([f"--test_arg={arg}" for arg in bzl_args[1:]])
+
+        env = {
+            **os.environ.copy(),
+            # Inject the debugger arguments into the rules_python toolchain.
+            "RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS": rules_python_interpreter_args,
+            # Ensure breakpoints hit the original source files, not Bazel's symlinks.
+            "PYDEVD_RESOLVE_SYMLINKS": "1",
+        }
+
+        # Execute Bazel.
+        result = subprocess.run(cmd, env=env, check=False)
+        sys.exit(result.returncode)
+
+    if __name__ == "__main__":
+        main()
+    ```
+    </details>
+
+2.  **Configure `launch.json`**: Add the following configurations to your `.vscode/launch.json`. This tells VS Code to use the launcher script.
+
+    <details>
+    <summary><code>launch.json</code></summary>
+
+    ```json
+    {
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Python: Bazel py run",
+                "type": "debugpy",
+                "request": "launch",
+                "program": "${workspaceFolder}/.vscode/debugpy/launch.py",
+                "args": ["run", "${input:BazelArgs}"],
+                "console": "integratedTerminal"
+            },
+            {
+                "name": "Python: Bazel py test",
+                "type": "debugpy",
+                "request": "launch",
+                "program": "${workspaceFolder}/.vscode/debugpy/launch.py",
+                "args": ["test", "${input:BazelArgs}"],
+                "console": "integratedTerminal"
+            }
+        ],
+        "inputs": [
+            {
+                "id": "BazelArgs",
+                "type": "promptString",
+                "description": "Bazel target and arguments (e.g., //foo:bar --my-arg)"
+            }
+        ]
+    }
+    ```
+    </details>
+
+    Note: If you find `justMyCode` behavior is incompatible with Bazel's symlinks (causing breakpoints to be missed), you can set `"justMyCode": false` in `launch.json` and use the `IDE_PROJECT_ROOTS` environment variable (set to `"${workspaceFolder}"`) to explicitly map your workspace.
+