Policy regarding python version specific stub changes

[JamesGuthrie]

With Python 3.5 collections.OrderedDict supports reversed() for views of its keys, items and values. In order for mypy to support this, the stub for collections needs to be updated. As a direct result though, mypy wouldn't detect illegal code for python < 3.5:

from collections import OrderedDict
OD=OrderedDict()
for k in reversed(OD.keys()):
    pass

This is a specific instance of a general problem: how do we deal with different typing behaviour from version to version of python? Should the stubs only keep up with the most current version of python? It would actually be better to always use the most version-specific version of a stub (i.e. stubs/3.3/collections.pyi if using py3.3), or to have the ability to tell mypy to type check against a specific minor version of python.

[o11c]

According to @gvanrossum, mypy should support if sys.version[:2] >= (3, 5) to check that.

That said, #721, among other things, will allow most-version-specific stubs, though I agree that's not a good design.

[JukkaL]

Currently the simplest approach is probably to just have all stubs track Python 3.5 and mark any features not present in older versions using comments.

However, having sys.version checks in the stubs would not hurt, as mypy would currently just treat them as no-ops. For this we'd just need to document the notation that mypy will support and start migrating stubs to use it. Eventually mypy would recognize these checks and allow specifying the target Python version against which to type check. We should probably coordinate with typeshed and/or typehinting as well.

[o11c]

I would like to see mypy have an "reverse stubgen" where it actually imports the module to see if all the functions really are there.

[JelleZijlstra]

This is obsolete as mypy now supports sys.version_info checks, and typeshed uses them widely.