GeezerVison is showing github.com — Add more specific error message when file has same name as an imported module · Issue #95754 · python/cpython
Add more specific error message when file has same name as an imported module #95754DescriptionFeature / 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
Linked PRs
Reacted by Ionite, Richard Si, Xithrius, D0rs4n, GDWR, ChrisJL, Jannes Jonkers, Gustav Odinger and Felipe S. S. Schneider ActivityKinza-Raza commented on Aug 8, 2022 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 commented on Dec 1, 2023 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. Reacted by Hugo van Kemenade, Shantanu, Alex Waygood and familyboat vstinner commented on Dec 1, 2023 ericsnowcurrently commented on Dec 1, 2023 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 commented on Dec 21, 2023 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? added a commit that references this issue on Apr 23, 2024gh-95754: Better error when script shadows a standard library or thir… hauntsaninja commented on Apr 23, 2024 Okay, I implemented a more thorough set of new error messages in #113769 taylor7936 commented on Sep 29, 2025
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|