Added support to .pyi stubs.

[rockneurotiko]

Pull Request for #345 that now is in "priority"

I had to make some decisions, like that init.py don't change the extension, shouldn't be a stub, and python use it to know the modules.

Also, to allow import scripts, the script sometimes look just .pyi files, and other times look .py and .pyi (first .py).

If don't if that's the solution you want.

[JukkaL]

Thanks for implementing this! A few quick notes:

• I don't want to rename any built-in stubs to use the .pyi extension (at least not yet). The .pyi extension will be an option for those who want to distinguish stubs, but .py still works fine.
• If there is both a .pyi and a .py file in a directory, the .pyi file should take precedence. This allows adding stubs/annotations to a module without touching the module source code and without creating a subdirectory for stubs, which can be handy for third party code and quick experiments, for example. It seems that currently the .py file is given precedence if both exist.

[rockneurotiko]

Hi!

• I thinked that you wanted to change the actual mypy stubs extension. Do you want it with .py extension?
• Search for .pyi first is better in that cases, yes. I've changed this, when I run the tests and see that nothing breaks I'll push to my branch.

[JukkaL]

Originally I considered switching all stubs to use the .pyi extension, but it would have some pretty major drawbacks such as not getting syntax highlighting by default. So I'd like all mypy std library stubs in the repo to continue using the .py extension, but users would have the option of also using the .pyi extension. I think that the main use cases for .pyi are these:

1. Have both a .py and a .pyi file in the same directory. Mypy will only use the .pyi file and ignore the .py file. This can be useful if mypy doesn't support some constructs in the .py file or if it's awkward to modify the .py file (for example, if it's owned by another team or copied from a third party project or needs to be Python 2 compatible).
2. Have only a .pyi file in a project. When running the program, the .pyi file will be ignored and the module will be imported using sys.path. However, mypy will not search for the module and will just use the .pyi file. This can be useful when using library modules that don't have stubs yet.

Another option for the case with both a .py and a .pyi file would be to merge the files (i.e., use annotations from .pyi file to type check code in the .py file) but I think it could be somewhat painful to keep the two files in sync. We can reconsider this use case in the future, but I don't see any immediate need to support this.

[rockneurotiko]

I've reverted the stubs extensions and added two simple tests.

Also, I've changed the PR name.

[JukkaL]

It looks good!