Warn about shadowing stdlib modules

[brettcannon]

Beginners often make the mistake of shadowing a module in the stdlib with their own code (e.g. creating a module named queue.py will break debugpy).

Since Pylance has the knowledge of what's in the stdlib as well as the names of the modules the user has, it could provide a diagnostic at either/both the import line that is getting shadowed or in the module causing the shadowing.

[erictraut]

The challenge here is that this situation isn't a false positive. It's not an error to shadow a module in stdlib. Furthermore, the set of stdlib imports continues to grow each release, so a code base that doesn't shadow a stdlib module might suddenly find itself doing so. I don't think we could enable such a check by default. That means it would need to be an optional check that users need to enable if they want to use it, but novice Python users wouldn't know to enable it.

[brettcannon]

You're right that false-positives are possible as there are legitimate reasons to shadow the stdlib (I've done it myself). But the vast majority of folks who do it are doing it by accident. So being opt-out might be a pragmatic solution.

And yes, the stdlib is not static over Python's lifetime. But the list of names per Python version is static and Pylance typically knows what version of Python is being run. And in the cases where Pylance doesn't know you can either worst-case it with all historical names or the newest version of Python released.

I've let the Jupyter team know about this issue as they have brought this specific case up before as an issue their users run into regularly.

[rchiodo]

We probably have telemetry on how often this prevents a user from running a jupyter kernel. But we've had a bunch of issues come in that ended up being this exact problem. We've added our own warning in the jupyter extension, but pylance can do a much better job.

[rchiodo]

/cc @DonJayamanne

[DonJayamanne]

majority of folks who do it are doing it by accident. So being opt-out might be a pragmatic solution.

Agreed, when we attempted to add a solution for this in the Jupyter extension, thats the approach we took (& made the same assumption).

this prevents a user from running a jupyter kernel.

As mentioned by Rich, in the case of Jupyter, if a novice user creates a simple file named random.py or email.py, that basically breaks jupyter completely, as the extension is unable to start the kernel.
I.e. at this point the functionality exposed by Jupyter extension is broken.

We probably have telemetry on how often this prevents a user from running a jupyter kernel.

I'd need to see if we have this today. If not, i'll add this.

[luabud]

We've seen some beginners face this issue on user studies in the past for Python in general. I do think it would be good to warn users about this issue by default, and allow more advanced users to dismiss the warning.

[mscuthbert]

I am seeing reportShadowedImports even when nothing is being shadowed in the file.

Working in a large project where I'm the owner of one part and not all. In another part of the project there's a file called "typing.py" (shadowing the stdlib typing) which has a lot of standard type classes for the project. That might be a problem for them to consider, but I can use it without shadowing the stdlib library. When I do:

from .typing import DictInterface

I get a reportShadowedImports error, with the suggestion to rename typing.py (which isn't part of my jurisdiction). But nothing is being shadowed in my file! Since (custom) typing.py is never imported into the file, only DictInterface, any prior imports of (stdlib) typing still work.

[debonte]

@mscuthbert, please open an issue on this.

[watfordkcf]

How do we disable this on a per file or per import basis?

Specifically from typing_extensions import override. I'm warned that this is being shadowed by my venv, except if I remove that line there is no way to use override without that import from the installed package in my venv. override is a Python 3.12ish thing as far as I'm aware.

[luabud]

@watfordkcf it'd be great if you could open an issue about this, please. You can do so by running the "Pylance: Report Issue" command from VS Code itself (View > Command Palette...)

[watfordkcf]

#4762

[ncoghlan]

I just ran into a case where PyLance claimed that pathlib was being shadowed by the standard library's own pathlib file: #6091