stdlib: Maximum supported version

[srittau]

This came up in #5284 and at other places before: Currently we have no way to signal that a stub was removed from the stdlib. We hack around this by using a top-level version_info check, but that's not ideal.

I suggest we make use of the stdlib/VERSIONS file we have since the restructuring. Extend it a little so that no only versions are allowed, but also version ranges:

foo: 3.8
bar: 2.7-3.8

This would need a change in type checkers to parse the new format, but a simple first solution is to just add an equivalent of version = version.split("-")[0].

Cc @rchen152 @erictraut @mrkmndz

[erictraut]

I didn't realize there was a VERSIONS file, so pyright doesn't currently pay attention to it. I should add that support. I'm fine with extending the format to include ranges.

[Akuli]

While we're at it, I think we could change the notation for "new in Python 3.8". Instead of foo: 3.8, how about foo: 3.8+ (very obvious) or foo: 3.8- (consistent with range notation)?

[rchen152]

Allowing version ranges sounds useful. Shouldn't be difficult to support in pytype.

I like @Akuli's proposal to change the "new in 3.x" notation.

foo: 3.8
bar: 2.7-3.8

looks like it would mean that the foo stub is for 3.8 exactly and no other versions. I don't have a preference between 3.8+ and 3.8-.

[srittau]

I have implemented the 3.8- format in my mypy PR for simplicity of implementation.

[srittau]

I submitted PRs to mypy (python/mypy#10402) and pytype (google/pytype#903). Since pyright and as far as I can see pyre don't support VERSIONS yet, we can implement this once the two PRs are merged.

[erictraut]

I have a PR that implements this support in pyright: microsoft/pyright#1819. It handles the following formats: 3.8, 3.8-, 3.8+, 3.6-3.9.

[hauntsaninja]

One other edge case here is submodules that were added or removed in Python versions, e.g. asyncio.compat (removed in 3.7) or asyncio.threads (added in 3.9). Currently we don't list any submodules in VERSIONS.

[JelleZijlstra]

We could extend the format to say asyncio.compat: 3.5-3.7. Existing implementations would (I believe) just silently ignore such bounds for now.

[srittau]

Jelle's suggestion sounds good, but we should double check.

[JelleZijlstra]

Here are the implementations:

• pytype at https://github.com/google/pytype/blob/master/pytype/pytd/typeshed.py#L103 – should work and just add useless entries to the dict
• typeshed-client at https://github.com/JelleZijlstra/typeshed_client/blob/master/typeshed_client/finder.py#L256 – same
• mypy at https://github.com/python/mypy/blob/4518b55663bc689646280a0ab2247c4a724bf3c0/mypy/modulefinder.py#L747 – same
• pyright currently ignores VERSIONS
• I couldn't find an implementation in pyre; it might also ignore VERSIONS