I've been frustrated so many times by `ImportError: cannot import name foo`. Right now I'm debugging some problem on a PAAS server (with no SSH access), and the server returns a traceback of `cannot import name foo`, and I don't have any idea what it means. It could mean that the file isn't there. It could mean that there's a circular import problem. Sometimes it happens when you go over Windows XP's path length limit!

Please provide a useful explanation, like this:

    ImportError: Cannot import `foo` because no file foo.py* or folder foo exists.
    ImportError: Cannot import foo module because no __init__.py* file exists in the foo folder.
    ImportError: Cannot import foo because of a circular import problem with bar.
    ImportError: Cannot import foo because the foo module file's path is bigger than Windows XP's path length limit.

Etcetera for any other reason that might cause an `ImportError`.

Rather than mucking with the string, we should probably set some of these details as attributes on ImportError. #10854 wanted something similar - details on the pyd file that failed if you get an ImportError on an extension module on Windows.

As long as those attributes are reflected in the string in human language, why not.

The problem with this request is it is practically unworkable. For instance, the missing __init__.py already exists as an ImportWarning. The circular import is a problem as Python would have to detect circular imports which is hard, else we would have a circular import solution. =)

We could fix the ImportError when running into stupid XP issues, but that requires someone to submit a patch enough to care to fix it. =)

What's the problem with detecting circular imports? Mind you that we only need a post-mortem analysis to check why the import failed; so after the import failed, we could check whether our import stack has a loop in it.

I'm not familiar with the ImportWarning regarding `__init__.py`. Is this written about anywhere?

Just a side note: please don’t use “folder” for cross-platform code or documentation, it’s a Windows-specific term (like “wizard” for example).

Doing a stack walk to try to determine if an import failure was from a circular import would be costly, a little complicated (since you cannot simply look at import statements but also various kinds of functions that can do an equivalent job of importing) and probably not worth it.

As for ImportWarning, it's at least mentioned in the exception hierarchy and the warnings docs.

Brett: Why does it matter that it will be costly? It's a post-mortem activity anyway, usually done when something critical failed and the entire system isn't working.

Why would functions need to be looked at? I mean, isn't a circular import when you try to import a module `foo` while in a lower stack level you haven't finished importing `foo` yet? Does it get trickier than that?

Brett, I checked out the two pieces of documentation you referred to, they have very little information about ImportWarning other than "Base class for warnings about probable mistakes in module imports."

Yes, there are ways other than an import statement that a module can get imported (the __import__ function, for example, and the imp module for another, as well as importlib).

If you want to try your hand at writing a patch to do the post mortem you will discover that import in Python is...complicated.

David, I don't think you've read my message carefully enough. I'm well aware that there are other ways in Python to import than the `import` statement. I'm proposing that it doesn't matter.

I asked, "isn't a circular import when you try to import a module `foo` while in a lower stack level you haven't finished importing `foo` yet?" If this is true, then you just need to have some kind of flag for each module saying "This module is currently being imported", which you set to `True` when you start importing and back to `False` when you finished importing. (It doesn't have to look exactly like this, it could be a context manager, or alternatively a centralized list of all module that are currently in the middle of an import.) Then when you have an `ImportError`, you check whether the module that the user tried to import has that flag raised, and if so notify him that it's probably a circular import problem.

Will that work?

It might.  Although I did miss your message about the flag, my point really was that you'll find that import is very complicated when you try to write the patch to do it.  There may not be one central place you can set and query that flag, because of the various ways import can happen and the byzantine nature of the import code.  It doesn't seem likely that anyone on the current team is going to tackle tying this, but you are welcome to.  We always need more contributors.  Just bear in mind that we weigh the benefits of patches against the additional code complexity they introduce (if they do; the most fortunate patches simplify things).  I think that's what Brett meant by "probably not worth it".

Brett wrote importlib to move a lot of the complication into Python code where it would be easier to work with.  That transition hasn't happened yet.  I hear that the import-sig is talking about doing some interesting things to (hopefully) make life better for everyone, so you might want to sign on there and find out what is going on before starting on a patch.

For the ImportWarning docs, there could stand to be more; patches welcome. =)

As for ImportError being postmortem on an error, that is not always true as plenty of people use the trick, e.g.:

try: import json
except ImportError: import simplejson as json

As for detecting circular imports, flagging it somehow might work, but directly analyzing the stack won't do since that is extremely costly on some VMs.

Thanks for explaining, I guess it's too complicated.

Closing as circular imports are not as much of a problem in Python 3.3, ImportError now has informational attributes, and namespace packages took care of the usefulness of ImportWarning.