docs: How to debug your main script from VS Code

[mmartinortiz]

Resolves: #7592

After having some difficulties to debug the main script of my program while using VS Code, I found this answer that helped me to solve my issue. I thought that would be worth for others to have this piece of information within Poetry's documentation.

[radoering]

I do not think we should recommend adding poetry to the dev dependencies of the project because this can lead to unexpected behavior. I am not a VS Code user, but I assume you can just configure the correct interpreter (the one returned by poetry env info) and run your entry point directly with this interpreter to debug it.

[mmartinortiz]

I am not a VS Code user, but I assume you can just configure the correct interpreter (the one returned by poetry env info) and run your entry point directly with this interpreter to debug it.

This is one of the multiple things I tried. Since poetry does not install the package being developed into the virtual environment, the interpreter cannot resolve the imports made from your own module. (At least, that is how understood it while I tried to make it work)

I found some threads in StackOverflow (this one is just an example) about how to get VS Code debug working for a project managed with poetry and I never found a working solution, except for this one, that install poetry as development dependency.

I can understand that it is not neither an elegant or robust solution and I'm very happy to document a more elegant method :-)

[radoering]

Since poetry does not install the package being developed into the virtual environment,

Poetry installs the package into the virtual environment in editable mode (except for when you set package-mode = false). You should find a *.pth file named after your project in the site packages of the virtual environment after running poetry install.

[mmartinortiz]

The documentation states that package mode is the default behavior. This is true for my project; however, unless I install poetry as a development dependency, I encounter a 'Module not found' error, and I can't get debugging to work in VS Code.

Clearly, my assumption about the reason for the module not being found was incorrect. What could be then the reason for the debugger to not find the error?

[TheSven73]

vscode debugging works for me without having to install poetry as a development dependency.

First, make sure vscode is using the venv which poetry has created. Run poetry env info and copy the location of the executable. Then, in vscode, run "Python: Select Interpreter" -> "Enter Interpreter path" -> paste the executable location. The bottom right of the vscode window should now show something like this

My main function is located in src/hypermodern_python/console.py:

import click

@click.command()
def main():
    click.echo('Hello, world!')


if __name__ == "__main__":
    main()

Next, create a launch.json which specifies the module which contains main:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "My script",
            "type": "debugpy",
            "request": "launch",
            "cwd": "${workspaceFolder}",
            "module": "hypermodern_python.console",
            "justMyCode": false,
        }
    ]
}

Place a breakpoint, run "Debug: Start Debugging" in vscode, and the breakpoint should be hit.

[mmartinortiz]

Thanks @TheSven73 , with your launch.json file I managed to debug my main script. I'm not sure how it different to other attempts, maybe it is just combination of justMyCode and module

I've updated my pull request with your instructions.

[TheSven73]

I'm not sure how it different to other attempts

Not sure either, hard to tell without a reproducible description of your attempt(s) (config+code).

[Secrus]

Drive-by question: if we were to include that in docs, what about other editors? Why should we have a special treatment for VS Code?

[mmartinortiz]

Drive-by question: if we were to include that in docs, what about other editors? Why should we have a special treatment for VS Code?

From my point of view, this is not giving a special treatment to VS Code.

When I found myself in need to debug a project managed with Poetry, setting it up in VS Code was not as straight forward as it is for projects not managed with Poetry. After searching for "how to do it" I found more people straggled with this, proposing different alternatives.

After I succeeded, and given that more people struggled with this, I thought would be worth to share the "how to" together with poetry's documentation.

[TheSven73]

I'm not convinced we have a clear definition yet of the problem we're trying to solve.

I just tried the official Microsoft tutorial to debug Flask and it works like a charm with Poetry. The only difference is that the developer must point vscode to the venv created by poetry, instead of hand-rolling their own using python -m venv and pip.

Can someone in the linked issue(s) can provide a clear and reproducible problem statement? Other than: "must tell the user to point vscode to the poetry venv", because that's true for other editors as well.