Import handling is confusing and misleading

[nedbat]

I tried mypy and was alarmed to see it unable to find imports that are clearly available. Reading the explanations in #1293 and #1339, I now understand why it doesn't merrily parse third-party code that will only add to a growing pile of unannotated code.

But this is a really bad first experience. I install something that claims to understand Python code, and it's confused by imports? Then it gives me two suggestions, neither of which is seems like the right advice:

note: (Perhaps setting MYPYPATH or using the "--ignore-missing-imports" flag would help)

I shouldn't try to set MYPYPATH, that's silly busy-work that if successful will only lead me into the unannotated third-party module trap. The imports aren't missing, so why would --ignore-missing-imports help? NOTE: using --ignore-missing-imports silences the warnings, but the option is misnamed: the imports are not missing.

Reading the help, I see --follow-imports, so I try those options. I try --follow-imports=silent, but that still complains about the imports. I try --follow-imports=skip, and that also still complains about the imports. Both of these sound like exactly what I need, and neither changes the behavior much:

$ mypy --version
mypy 0.560
$ mypy census.py
census.py:16: error: Cannot find module named 'aiohttp'
census.py:16: note: (Perhaps setting MYPYPATH or using the "--ignore-missing-imports" flag would help)
census.py:17: error: Cannot find module named 'async_timeout'
census.py:18: error: Cannot find module named 'attr'
census.py:20: error: Cannot find module named 'opaque_keys'
census.py:21: error: Cannot find module named 'opaque_keys.edx'
census.py:21: error: Cannot find module named 'opaque_keys.edx.keys'
helpers.py:3: error: No library stub file for module 'lxml'
helpers.py:3: note: (Stub files are from https://github.com/python/typeshed)
helpers.py:4: error: No library stub file for module 'lxml.html'
$ mypy --follow-imports=silent census.py
census.py:16: error: Cannot find module named 'aiohttp'
census.py:16: note: (Perhaps setting MYPYPATH or using the "--ignore-missing-imports" flag would help)
census.py:17: error: Cannot find module named 'async_timeout'
census.py:18: error: Cannot find module named 'attr'
census.py:20: error: Cannot find module named 'opaque_keys'
census.py:21: error: Cannot find module named 'opaque_keys.edx'
census.py:21: error: Cannot find module named 'opaque_keys.edx.keys'
$ mypy --follow-imports=skip census.py
census.py:16: error: Cannot find module named 'aiohttp'
census.py:16: note: (Perhaps setting MYPYPATH or using the "--ignore-missing-imports" flag would help)
census.py:17: error: Cannot find module named 'async_timeout'
census.py:18: error: Cannot find module named 'attr'
census.py:20: error: Cannot find module named 'opaque_keys'
census.py:21: error: Cannot find module named 'opaque_keys.edx'
census.py:21: error: Cannot find module named 'opaque_keys.edx.keys'
$ mypy --follow-imports=error census.py
census.py:16: error: Cannot find module named 'aiohttp'
census.py:16: note: (Perhaps setting MYPYPATH or using the "--ignore-missing-imports" flag would help)
census.py:17: error: Cannot find module named 'async_timeout'
census.py:18: error: Cannot find module named 'attr'
census.py:20: error: Cannot find module named 'opaque_keys'
census.py:21: error: Cannot find module named 'opaque_keys.edx'
census.py:21: error: Cannot find module named 'opaque_keys.edx.keys'
census.py:23: note: Import of 'html_writer' ignored
census.py:23: note: (Using --follow-imports=error, module not passed on command line)
census.py:24: note: Import of 'site_patterns' ignored
census.py:27: note: Import of 'sites' ignored
$ mypy --ignore-missing-imports census.py
$

[gvanrossum]

Sorry you are having such a bad experience. Maybe PEP 561 will (eventually) make things better. And maybe we can improve the error messages.

In the meantime, in order to understand your predicament better, can you link to the contents of census.py, and explain where the things mypy couldn't find are installed?

[nedbat]

census.py is here: https://github.com/edx/openedx-census/blob/4b242cc72896db002d9818a06bcdebdcdd6f8480/census.py

All of the imports mentioned in the error messages above are installed in the same virtualenv that mypy is installed into. Simply running "import aiohttp" succeeds, for example.

[gvanrossum]

So for aiohttp the solution would be for someone to add stubs to typeshed, or to create a separate package of stubs using PEP 561 (soon to be accepted and implemented).

If you have a habit of splitting your 1st party project into multiple packages that are installed separately (IIUC that's what you do at Edx) that's also a bit of a problem for mypy compared to the workflow where most code is in a unirepo (like we do at Dropbox, and IIUC that's also how Instagram and other large current mypy users do it), since with the unirepo approach you only get this problem for 3rd party packages, which are usually in typeshed. This is also what --ignore-missing-imports was made for. I do think that PEP 561 should also help for your multi-repo approach.

[nedbat]

You mention missing stubs. Perhaps this is the heart of the matter? The message says "missing imports", and what it means is, "missing stubs"? Or, I read it as trying to import Python, but it's trying to import stubs? Adding a few more words could clarify things.

FWIW: Although this code is in the edx org and about Open edX, it is a small-ish standalone program.

[gvanrossum]

Not quite standalone (opaque_keys seems to be an edx package).

Maybe "missing imports" is indeed not the right term. When mypy sees import foo it looks for the code in a path that is constructed from $MYPYPATH plus the files from the command line (with some tweaks). In each directory along the path it looks for both a stub (foo.pyi) and a Python module (foo.py) and a package (foo/). When it doesn't find something, it doesn't know what's missing. So what should it say?

PS. People tend to counter "why doesn't it use $PYTHONPATH or sys.path" but that really doesn't work because the majority of code on sys.path is stdlib code which has no annotations and triggers complaints about all sorts of edge cases.

[glenjamin]

I've just started playing around with mypy and run into this same confusion.

I think that something like "missing type definitions or type-annotated code for module foo" might be a more precise error message for this scenario.

I initially tried to get my environment to find the code, but what I actually need to do is provide type definitions for these modules in some way.

[glenjamin]

The flow project from facebook has a similar scope to mypy - i'm not sure whether or not I had a similar experience when beginning to use that project, but their docs section on how to work with library definitions seems relevant here: https://flow.org/en/docs/libdefs/

[ilevkivskyi]

I think we could wait a bit until PEP 561 is implemented, then we can design a better error message that will better detect the situation and proposes possible solutions (with a link to the docs, like we do for a common error with invariant collections). @ethanhs what do you think?

[emmatyping]

Yes, I think once #4693 is merged it would be good to take a look at updating and improving the missing module messages. Especially considering some of them (such as those that reference typeshed) may be misleading after PEP 561 packaging becomes the norm.

[jtratner]

I was quite confused by this too (at first I thought it was a virtualenv thing). Would folks be open to a page in the docs that has a separate section (for easier searchability) that looks like:

Common Errors
===========

Cannot find module named <foo>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Some modules do not have stub files (yet!). When mypy encounters an import that cannot resolve to a stubfile... <copy from existing docs>

Also, perhaps changing the error message from:

census.py:16: error: Cannot find module named 'aiohttp'

to

census.py:16: error: Cannot find type stubs for module named 'aiohttp'

would make things clearer. "Cannot find module" is very similar to the ModuleNotFoundError you get on a typo on import.

[gvanrossum]

How do you propose mypy should tell the difference between a module without a stub and a typo? It does not use the same module search path as the Python interpreter. For known standard library modules and for well-known third-party modules it does produce a different error message -- see the logic at

mypy/mypy/build.py

Lines 2059 to 2072 in 6784d85

	elif ((manager.options.python_version[0] == 2 and moduleinfo.is_py2_std_lib_module(target))
	or (manager.options.python_version[0] >= 3
	and moduleinfo.is_py3_std_lib_module(target))):
	errors.report(
	line, 0, "No library stub file for standard library module '{}'".format(target))
	errors.report(line, 0, stub_msg, severity='note', only_once=True)
	elif moduleinfo.is_third_party_module(target):
	errors.report(line, 0, "No library stub file for module '{}'".format(target))
	errors.report(line, 0, stub_msg, severity='note', only_once=True)
	else:
	errors.report(line, 0, "Cannot find module named '{}'".format(target))
	errors.report(line, 0, '(Perhaps setting MYPYPATH '
	'or using the "--ignore-missing-imports" flag would help)',
	severity='note', only_once=True)

. Perhaps you can provide an update to the list of well-known third-party modules? (It is in https://github.com/python/mypy/blob/master/mypy/moduleinfo.py.)

It's probably true that we need to improve the docs explaining how mypy finds modules though -- clearly this is a frequent source of confusion. (Many people assume mistakenly that mypy loads everything from sys.path.)

[jtratner]

Would you be open to outputting a doc link that goes directly to a page explaining how all of this works? (Happy to write up something if so) Pandas does this for setting vs copy and I think it’s an elegant way to handle a confusing issue :) My gut instinct when I saw that error was to repeatedly try to get mypy to run within the virtualenv or try to set it up to point at the right PYTHONPATH. (Now I totally get it but not really until I read this github issue) Would it be possible to check if the module is importable and generate a different error? (Maybe this violates static typing) :)

…

On Sun, Apr 8, 2018 at 9:09 PM Guido van Rossum ***@***.***> wrote: How do you propose mypy should tell the difference between a module without a stub and a typo? It does not use the same module search path as the Python interpreter. For known standard library modules and for well-known third-party modules it does produce a different error message -- see the logic at https://github.com/python/mypy/blob/6784d85a084ff1d782fe5b3d6ab1331d27d49791/mypy/build.py#L2059-L2072. Perhaps you can provide an update to the list of well-known third-party modules? (It is in https://github.com/python/mypy/blob/master/mypy/moduleinfo.py.) It's probably true that we need to improve the docs explaining how mypy finds modules though -- clearly this is a frequent source of confusion. (Many people assume mistakenly that mypy loads everything from sys.path.) — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#4542 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABhjqycjzKO8IS4pHtvWr8i_NLSpu6Ygks5tmt7-gaJpZM4R5VzC> .

[keysmashes]

For known standard library modules and for well-known third-party modules it does produce a different error message

I wonder if producing a different error message for known third-party packages is actually more confusing… Such a list of packages will inevitably be incomplete, and it's not clear as an end user why some of your dependencies are being treated differently to others.

[gvanrossum]

I'm fine with doing all that but please submit a PR that both adds some docs and adds a note to the error message that links to it. And please test it as well as you can. (Your gut instinct was definitely wrong, so we clearly need to do some user education here. :-)