documentation on how to configure MYPYPATH is needed

[samuelcolvin]

In trying to provide more information on #1319 I ran into lots of problems with trying to set MYPYPATH. There doesn't seem to be any documentation on how it should be set.

For example my library has the following __init__.py file:

from distutils.version import StrictVersion
VERSION = StrictVersion('0.0.1')

This seems to cause mypy a lot of problems.

My project uses virtualenv and pip to install packages, sys.path looks as follows:

['',
 '/home/samuel/code/harrier/env/lib/python35.zip',
 '/home/samuel/code/harrier/env/lib/python3.5',
 '/home/samuel/code/harrier/env/lib/python3.5/plat-x86_64-linux-gnu',
 '/home/samuel/code/harrier/env/lib/python3.5/lib-dynload',
 '/usr/lib/python3.5',
 '/usr/lib/python3.5/plat-x86_64-linux-gnu',
 '/home/samuel/code/harrier/env/lib/python3.5/site-packages']

What value should I set MYPYPATH to to allow checking a script including distutils.version? All the things I tried failed.

I think partially related to #1293.

[gvanrossum]

In general it's not a great practice to try and let mypy follow all imports to 3rd party packages; it usually leads to complaints about those 3rd party packages and/or poor checking because the typical 3rd party package doesn't have annotations.

A better approach is to develop stubs for the 3rd party modules that you care about, and then (with approval of the 3rd party module's developers) contribute them to https://github.com/python/typeshed.

[gnprice]

While you don't yet have stubs for some third-party modules you're using, a very helpful flag to use is --silent-imports:

  -s, --silent-imports, --silent
                        don't follow imports to .py files

This has the effect that when mypy sees an import of a module and it's neither

• another module you asked mypy to type-check on this command line, nor
• a module mypy sees a stub (a .pyi file) for,
  mypy just treats that module and everything imported from it as untyped.

A typical command line would then look like mypy -s mycode/ morecode.py, where you identify your own codebase that you want to type-check by directory trees and/or individual files listed on the command line. Then mypy type-checks precisely that code, which lets you move ahead with putting type annotations on your own code.

Probably the best workflow for you will be to use a command line like that, and then also as you find yourself wanting types on things imported from third-party libraries write stubs for them.

---

We should still also document MYPYPATH clearly! Particularly as some libraries may start adopting type annotations, or as you might add annotations to libraries of your own which your other code depends on. To help us most effectively document it, can you tell us where you looked when trying to figure it out?

[samuelcolvin]

oh, excellent, -s is what I was looking for.

Perhaps it should be set by default?

If not set by default I would suggest that (Perhaps setting the "-s" option would help) would be a more helpful suggestion than (Perhaps setting MYPYPATH would help). Or perhaps a mention of both with a link to documentation?

[gvanrossum]

Documenting everything around -s and MYPYPATH clearly is important. (See also #1367.) The docs should emphasize that when you're confronted with a stdlib or 3rd party module or package for which stubs aren't in typeshed yet, you most likely don't want to extend MYPYPATH to analyze the module/package itself. (For stdlib modules, mypy has a list of known stdlib modules used to change the error message when a stdlib module has no stub; but for 3rd party modules it's pretty hopeless to try and maintain such a list.)

[gvanrossum]

I consider this done with 4825e34 (note: readthedocs hasn't been synced, I think @JukkaL needs to do something to the webhook).