Improve messaging when an import could not be resolved

[cwebster-99]

Background

A common hurdle new users encounter when using Python in VS Code is package installation. Those new to Python programming and working with editors find it challenging to understand the concepts of installing and importing packages, using pip, and managing environments. This complexity can lead to frustration and some users may even abandon Python in VS Code, perceiving it as unfriendly and intimidating for beginners.

Audience

The target audience for the proposed mockup is beginners who may not be comfortable or familiar with the idea of environments or third-party packages.

Current Behavior

Unresolved import messaging from Pylance

Current Code Actions

Proposed Behavior

To address some of the confusion around environments and package installation, we should provide specific Code Actions and/or specific messaging tailored for users that are not using an environment with their specified packages or struggle to resolve import errors.

💡“Select another interpreter”

• If a Quick Fix - Link to Python: Select Interpreter command
• Could be a hint or tip on hover

💡 “Learn how to install packages” (microsoft/pylance-release#3297)

• Link to documentation (We don’t specifically have documentation on import errors. Should we create a new page or add this to an existing one?)
  https://code.visualstudio.com/docs/python/environments
  https://code.visualstudio.com/docs/python/editing#_troubleshooting-intellisense

Option 1: Present options in the Quick Fix list

Option 2: Provide a link at the bottom of the Quick Fix list and provide more info on hover

Example from TS:

cc @luabud

[rchiodo]

I think we should also add a better message to the message from Pylance. We have an issue for that here:
microsoft/pylance-release#4368

[cwebster-99]

@rchiodo Are you referencing this message (the tip added for the purpose of the spec)

Would the messaging you have in mind be to list the current environment the user is working in and then suggest switching or creating a new environment?

[rchiodo]

I was thinking it would say something like so:

Import "flask" could not be found in the ".venv" environment. (reportMissingImports).

Then the tip you have would show up.
And the quick actions would have the options you mentioned above.

[rchiodo]

I think the hard part here is adding that 'Tip' item. It would be relatively easy for us to add it on the Pylance side, but having the Python extension do so would be a lot harder.

[rchiodo]

I also think the two options you have would be good combined as well. So the entire change would be:

Message:

Import "flask" could not be found in the ".venv" environment. (reportMissingImports). Tip: Ensure you are using the correct interpreter

Quick actions:

• Select a different interpreter
• Create a new venv with flask installed
• Install flask into your .venv interprer
• Learn more about interpreters

With maybe the middle two actions not in the MVP

[cwebster-99]

I really like this idea for the MVP!

My only concern about the "Select another interpreter" as a Code Action is that it does not directly add code. Maybe it would be sufficient to just have the tip in the message? @luabud Do you have an opinion on this?

[rchiodo]

I'm also thinking it makes the most sense for Pylance to make all of these changes. Otherwise, we're going to have to add something to diagnostics that allows the Python extension to figure out that it's an import error, and what package is missing.

[luabud]

Love the idea! Agreed with making this on the Pylance side. I wonder if it'd be possible to make the "select interpreter" command be triggered from a link in the tip? then it wouldn't need to be a code action?

[rchiodo]

I believe that's possible, but I'm wondering why not use a code action?

Pylance can initiate a command from a code action, so it's certainly possible to 'Select interpreter' in a code action from Pylance.

[luabud]

I guess I was coming from the point of view that it's not really a code action as code isn't being touched/changed but I chatting with Brett he did bring up that it might make code no longer fail to execute, so a code action still makes sense. No objections against code actions anymore from me :p

[cwebster-99]

Awesome! I think the MVP should be as Rich outlined above contributed by Pylance:

Message:

Import "flask" could not be found in the ".venv" environment. (reportMissingImports). Tip: Ensure you are using the correct interpreter

Quick Actions:

• Select a different interpreter
• Learn more ....

For the "Learn more", I think it would be best to add a section to https://code.visualstudio.com/docs/python/environments#_working-with-python-interpreters or https://code.visualstudio.com/docs/python/editing#_troubleshooting-intellisense with information on how to troubleshoot the error message. Preferences on one or the other?

[rchiodo]

Both :)

I mean if somebody is at either location, they should be able to learn the same information. Maybe both can point to another URL that describes the situation (or one points to the other).

[cwebster-99]

Closing this in favor of the microsoft/pylance-release#4368 that tracked this work from the Pylance side.