To which Python version should a stub's syntax conform to?

[srittau]

We had an interesting case recently with the introduction of Python 3.7: async and await became keywords, but async had been used as a function name in asyncio prior to that. That meant that the asyncio stub could not be parsed with Python 3.7 anymore.

Also, we usually want to support the latest language features in type stubs, so stubs can be written for modules making use of the latest language features. And of course since newer language features will often allow a better stubs (for example the variable annotation introduced in 3.6).

I think we should discuss this problem in the PEP, but how do we solve it? Should we mandate that stubs must always be parseable with the latest released Python version? Or just use a fixed version number (3.7?) for now? What about the type checker side?

[JelleZijlstra]

Perhaps we could institute a rule like:

• For the first six months after the release of Python version 3.x+1, stubs should be syntactically valid under both version 3.x and 3.x+1.
• After that, they only need to support version 3.x+1.

In fact though we started using variable annotations (new in 3.6) earlier than 6 months after 3.6 was released in December 2016 (compare python/typeshed#653). And asyncio.async() was still in typeshed when 3.7 was released.

[Solumin]

That would give maintainers six months to fix up all the pyi files in typeshed that have backwards compatibility issues, which seems reasonable.

It makes sense to me that a stub file should conform to the Python version of its associated source file. But that's a bit weak, since there's no standard way for a source file to indicate which version of Python it's written for, and stubs aren't associated with just Python source files. (e.g. stubs for C extensions.) Furthermore, the typeshed stubs for Python 2's stdlib are closer to Python 3, since they use Python 3's class syntax. And then there's the issue of how complex that would make the type checkers...

srittau, you mention "new language features." What kind of language features do you envision will be used in stub files?

[JelleZijlstra]

I think existing practice is to not follow the same syntax as the version of Python they're written for, notably in that Python 2 stubs use type annotations instead of type comments.

Here's some possible issues from the past that could have been affected by this decision:

• Can Python 2 stubs use type annotations instead of type comments?
• Can pre-3.6 stubs use variable annotation syntax?
• What do we do about usage of async as a variable name in pre-3.7 stubs?
• Can pre-3.6 stubs use the class-based NamedTuple syntax?

[srittau]

In the future I can see a more concise annotation syntax, for example for lists, tuples, or even callables. Or possibly new keywords or builtins that could be used in type stubs. Of course, I do not know what kind of features future Python versions will bring.

Recently there have been many new features for type hints and I think it's useful to be able to use them in stub files, even if they can't be used in the implementation. After all, stub files can be parsed independently from implementation code.

[srittau]

Closed in #17.