Add more specific error message when file has same name as an imported module

[janine9vn]

Feature / enhancement

Currently, if a python file I create and am trying to run has the same name as a module I'm importing in it (i.e. my file is named random.py and I try to do import random; print(random.randint(5)), the following error message appears:

AttributeError: partially initialized module 'random' has no attribute 'randint' (most likely due to a circular import)

Instead, for this particular scenario, a more specific error message would be helpful:

ImportError: random.py imported itself. File name should be different than the imported module name.

Pitch

Frequently, someone learning python will try to name their python files after the topic they are learning about. These topics can be about a specific module (e.g. random, turtle, pygame, requests). For instance, someone experimenting with the turtle module, might name their python file turtle.py. This results in the scenario of a person trying to import a module, but instead their program tries to import itself because of the name collision.

The current error message isn't clear that the issue is the filename conflicting with the module name and overriding it. Folks with more experience can deduce that from the "circular import" portion, but beginners are often confused by the "AttributeError" portion. I think this scenario would be a good candidate for a more specific error message, to better warn about this common pitfall.

The recent improvements for more detailed and specific error messages have helped many people, especially those new to Python. I think this would be a worthwhile addition in that same vein.

Considerations & discussion points

The example improved error message I have above is very much open to improvements, if folks have suggestions.
I am also operating under the somewhat informed assumption that there isn't a valid case for a file to import itself, so there would not be an issue with this error appearing if the imported module is the same name as the file itself.

Previous discussion

• https://groups.google.com/g/python-ideas/c/dNbXlL2XoJ8?pli=1

Linked PRs

• gh-95754: Better AttributeError on partially initialised module #112577
• gh-95754: Better error when script shadows a standard library or third party module #113769

[Kinza-Raza]

Hi @janine9vn 👋🏼

What version are you using? I tried this on version 3.9.13 and getting a slightly different phrased error

AttributeError: module 'random' has no attribute 'randint'

I agree, ImportError class would be better suited. Perhaps a better error message could be:

ImportError: in-built module 'random' unable to import due to conflicting file name

Open to suggestions, would love to take this up once finalised!

[carljm]

Thanks for opening this issue! I agree that we could likely make some changes to make this common situation easier to debug, especially for people new to Python.

I don't think that we should change the exception type from AttributeError to ImportError. The actual error that occurs in this case is an AttributeError (because of trying to access the randint attribute on a module that doesn't have it); even though the root cause here is import-related, changing the exception type obscures what actually happened, makes Python less consistent, and will make it harder to gain an understanding of how the import system actually works.

Fortunately, I think the exception type is not the most important thing here; I think we improve debuggability much more by changing the exception message itself. One simple change that I think would be worthwhile would be to add the file path to the module to the error message, so it would be more obvious that the random module being used is the one the developer created, not the stdlib one. So the error could look something like

AttributeError: partially initialized module 'random' from '/Users/carljm/tmp/random.py' has no attribute 'randint' (most likely due to a circular import)

There's more that we could consider, but I think even this much would be a pretty good start.

[vstinner]

Consider using -P command line option to not add the path to the executed script to sys.path: https://docs.python.org/dev/using/cmdline.html#cmdoption-P It allows running a custom random.py script which imports successfully random standard library module (import random).

[ericsnowcurrently]

FWIW, this reminded me of PEP 338, PEP 366, and one other proposal @ncoghlan had that outlined, IIRC, 4 things that needed fixing (I don't remember if it was a PEP or tracker issue).

[hauntsaninja]

We've implemented carljm's suggestion. Are there any other concrete suggestions on how to improve the error? We could try special casing standard library here and provide a different error message if the module name is in sys.stdlib_module_names?

[hauntsaninja]

Okay, I implemented a more thorough set of new error messages in #113769