Summary of Changes

Hello @shayanhoshyari, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the documentation for debugging Python applications built with rules_python. It introduces a new, detailed workflow for integrating debugpy with development environments like VS Code, providing users with a robust method to debug their Bazel-managed Python code. The changes clarify existing debugging options and offer a practical, step-by-step guide for a common debugging setup, making the debugging process more accessible and efficient for developers.

Highlights

• New Debugger Integration Guide: A comprehensive guide has been added for integrating debugpy (used by VS Code and PyCharm) with Bazel-managed Python projects, leveraging a custom launcher script and the RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS environment variable.
• Documentation Restructuring: The existing debugger documentation (debuggers.md) has been restructured to clearly differentiate between the --debugger flag method and the new RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS approach, improving clarity and organization.
• Environment Variable Clarification: The environment-variables.md document has been updated to explicitly state the utility of RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS for debugger integration and now links directly to the new debugger guide.
• Detailed VS Code Setup: The new guide includes detailed instructions, a Python launcher script (launch.py), and VS Code launch.json configurations to facilitate seamless debugpy integration for bazel test and bazel run commands.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request significantly improves the documentation by adding a comprehensive guide on integrating debugpy for use with editors like VSCode and PyCharm. The new section is well-structured and the included launch.py script is a very helpful addition for users. I've identified a bug in the script's handling of arguments for bazel test and a minor point of confusion in the launch.json configuration. Addressing these points will make this excellent contribution even better.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great, thank you for adding this!

--test_env=RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS

We should add that env var to the vars tests inherit.

Maybe also PYDEVD_RESOLVE_SYMLINKS and IDE_PROJECT_ROOTS? I'm not familiar with these, so not sure about them as much.

Import debugpy, provided by VS Code

Any idea how closely coupled the VS Code side and target-under-test side are? I'm thinking there's risk of version skew and weird errors to occur. Presumably, there's a network protocol the TUT is talking back to VS Code (this would imply a weaker coupling)? Or is the VSC debugpy side handling all that and translating it for VSC (this would imply a stronger coupling)?

Overall, I'm thinking: what would we need so that launch.json and the bridge script didn't need so much code? Looking at what you have here...

A "bazel vscode bridge" and/or "bazel debugpy bridge" pypi packages? And they do something like: at app startup, patch and muck with things to facilitate debugging. Something like import bazel_debug_hook or "use package metadata to find entry points of debug hooks to load" into the stage2 bootstrap? Putting something in stage1 seems harder; the extra-args env var pretty clean; maybe if --debugger took something from that target and put it into stage1? My overall goal is to simplify things so that the typical bazel-bin/foo_test or bazel test //:foo_test can Just Work

In any case, it's great to have some working option documented!

PYDEVD_RESOLVE_SYMLINKS and IDE_PROJECT_ROOTS

Here are the "docs" (in quotes since they are just github comments)

PYDEVD_RESOLVE_SYMLINKS

IDE_PROJECT_ROOTS

Any idea how closely coupled the VS Code side and target-under-test side are?

In theory the vscode and target under test python versions don't have to be the same. I tried 3.10 (vscode python) and 3.12 (target under test) and it looked okay. That being said it is possible to hook launch.json to use the bazel python, by adding these at the cost of more boilerplate 🙈

# launch.json
{
    ...
   "python" : ".vscode/python",
    ...
}

# .vscode/python
set -e

cd "$(realpath $(dirname $0)/..)"
exec bazel --quiet run \
    --run_in_cwd \
    --show_result 0 \
    @rules_python//python/bin:python \
    -- \
    "$@"

My overall goal is to simplify things so that the typical bazel-bin/foo_test or bazel test //:foo_test can Just Work

I thought a bit about this, but could not come up with a good answer.

Pip package

If we put launcher script in a pypi package. Then we can do

{
    ...   
   "module" : "bazel_shim.main", # replace .vscode/launch.py with this
}

But still how to get this module is a challenge. Because it needs to exist in the vscode python. Putting it in rules_python's requirements.txt won't help :( .

Write a vscode plugin

Or just go to bazel's vscode plugin. https://github.com/bazel-contrib/vscode-bazel

This probably can work out of the box, we can vendor the launcher script, and add a new debug target type. Cons are that: It is vscode specific (might be okay), and well more work as we need to write typescript and contribute to another repo.

I have been maintaining (very low effort) pytest-bazel PyPI package and I am convinced that for pytest it is the right level of abstraction. Maybe debugpy-bazel could be similar?