Alternative extension for stubs

[mvcisback]

In addition to looking for for python files in the stubs folder or specified by MYPYPATH, it'd be nice to a alternative extension .py.s or something that signified it's a stub for the matching module.

This would be particularly nice for python2.x support since one could define .py and .py.s or have mypy compile to both (like typescript -> javascript)

This would have a similar goal as #25

[JukkaL]

Sounds reasonable. This would have a secondary benefit of making it easy avoid accidentally importing a module stub as a real module. A minor issue is that default syntax highlighting in editors would not work for the stub files.

I'd probably prefer an extension with just a single dot. It also needs to be something that is not in use (it should not be used by cython, etc.). .pys seems to be used in Windows (or was). Maybe .pyi, where i stands for an interface definition?

Have you thought about how this would work exactly? Maybe go through all directories in the search path, and for each directory, first look for a file with the new extension and then for a file with the normal .py extension.

[mvcisback]

Pyi seems to have been taken. http://www.filesuffix.com/en/extension/pyi
How about .mypy?

As for getting it to work, I imagine it'd be best to emulate python's import scheme (which would involve going through all the directories in the search path).

I believe the resolution you described should work.

[JukkaL]

Not sure about .mypy, since these would be used for just a subset of files.

.pyi was used by Cognos, but apparently more recent versions use .pyj (8.x was released around 2009, based on some Googling), so I doubt there much room for confusion:

PYI file is a Cognos Model File. Cognos is a world leader in Business Intelligence solutions that improve and direct corporate performance. In Cognos Transformer version 8.x, models saved in binary format now use the .pyj file extension. In Transformer version 7.x, models saved in binary format used the .pyi file extension.

[mvcisback]

.pyi sounds good.

Is build.py the only module that needs to be touched to implement this?

[JukkaL]

Yes, I think only build.py needs to be touched.

[JukkaL]

Upped priority, as this is blocking #346.

[JukkaL]

This is now implemented, but we aren't going to change std lib stub extension to .pyi, at least for now. .pyi is just an alternative extension for stubs, which can be handy because Python VMs ignore these files. If both a .pyi and a .py file exists in the same directory, .pyi takes precedence.

Quote from me, from the discussion related to the above pull request (I should also mention that @gvanrossum was against changing the default extension):

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.

Another potential use case is making local changes to a mypy stub and using it with the .pyi extension.