Distribute stdlib types as types-stdlib

[srittau]

This has been briefly discussed before, but I think it would be a good idea if we started distributing the stdlib types in a separate package types-stdlib, similar to third-party packages:

• Type checkers could optionally depend on (a specific version of) that package, instead of shipping their own copy, reducing coupling and arguably improving maintainability.
• Third-party stubs could require a minimum version of the types-stdlib package, for example if they are relying on _typeshed features or for cases like Add setuptools stubs #5762. Type checkers that opt to distribute a copy of the stdlib, could warn if incompatible stubs are used.

Technical considerations:

• The versioning scheme would be similar to third-party stubs, e.g. types-stdlib 3.10.X, where X is incremented automatically. We should probably increment the version number as soon as the first beta is released and we are reasonably sure we have added all new/changed API.
• The stubs would be installed into a special directory, for example stdlib, or even a non-importable name like types-stdlib (so we'd have stubs stdlib/sys.pyi etc.) so that they are only used by type checkers that support this package and don't interfere.

[gruebel]

The versioning scheme would be similar to third-party stubs, e.g. types-stdlib 3.10.X, where X is incremented automatically. We should probably increment the version number as soon as the first beta is released and we are reasonably sure we have added all new/changed API.

Wouldn't it be better to go with a pre release suffix first, then start with 0, when also Python 3.10.0 is released and after that do the auto increment?
Or stay close with the Python version and increment the suffix part 3.10.0-123?

But I definitely like the idea 👍

[srittau]

We don't do that with third-party stubs either, since the third element has no influence on the API. Also, 3.10.0, for example, would not be a pre-release from typeshed's view. 3.10.x stubs are also viable for Python 3.9 and before, but additionally support Python 3.10.

[Akuli]

Idea: Rename stdlib to stubs/stdlib so that it is just like any other package, and also not confusingly outside stubs/ even though it contains stubs.

[Cheaterman]

This is an excellent idea! I was hitting #7085 / #7086 today, and I'd have loved to just upgrade types-stdlib to see it fixed :-)

[JelleZijlstra]

I would find this very useful, and pyanalyze would definitely use it. Currently I have to manually make a new release of https://github.com/JelleZijlstra/typeshed_client when I need it.

It might be better to use calendar-based versioning for the stdlib stubs. Using the Python version will likely confuse users into thinking that they can't use types-stdlib 3.11.x yet if they're still on 3.10. And we tend to add features from new Python versions gradually; there really isn't a clear point where it makes sense to increment a major version number.

[hauntsaninja]

Definitely agree on not using Python version for versioning here.

On the overall proposal, I'm a little hesitant, since type checkers are in fact coupled to standard library stubs: it's pretty common for PRs to typeshed to require changes to pyright, mypy and pytype. So while it's straightforward enough to decouple distribution, I'm not sure how we'd actually decouple semantics.

I'll also note that in my experience, users are really bad at managing typing dependencies. Most users don't pin stub packages (if they even know they exist) and are really slow to upgrade mypy. I've encountered several users of mypy versions from before I starting contributing to typeshed or mypy! So I'm vaguely worried about the potential for situations like someone ending up pulling in a new types-stdlib and an old mypy and having a bunch of things inferred as Any. We've already had this situation with third party stubs, but the impact on users is much worse for stdlib.

But maybe my fear is unfounded. And none of my fear applies if we consider this opt-in for tools that would find automatic packaging useful and we don't necessarily expect type checkers to support swapping out stdlib.

[srittau]

It might be better to use calendar-based versioning for the stdlib stubs. Using the Python version will likely confuse users into thinking that they can't use types-stdlib 3.11.x yet if they're still on 3.10. And we tend to add features from new Python versions gradually; there really isn't a clear point where it makes sense to increment a major version number.

I had the same thought just a few days ago, so that's a +1 from me.

[srittau]

On the overall proposal, I'm a little hesitant, since type checkers are in fact coupled to standard library stubs: it's pretty common for PRs to typeshed to require changes to pyright, mypy and pytype. So while it's straightforward enough to decouple distribution, I'm not sure how we'd actually decouple semantics.

While the situation has improved significantly over the last few years, I believe that for the time being, type checkers should either keep bundling typeshed or pin it to a specific "known good" version. As typing stabilizes, we can discuss a stability guarantee.

[Akuli]

It would be nice if type checkers simply offered a configuration option that makes them use types-stdlib instead of their bundled stdlib. This way most people will just use the bundled typeshed without any problems, but if someone wants newer stdlib stubs, that would be possible too.

Currently you have to include typeshed as a Git submodule and point mypy at it with --custom-typeshed-dir, which works but isn't ideal. I used to do that in one of my projects, but eventually I decided to just use mypy's bundled stubs, because the Git submodule thing confused every new contributor who worked on the project, and expected pip install -r requirements-dev.txt to just work. This means that I typically discover a couple bugs when I update mypy.

[srittau]

Two more thoughts:

Instead of starting with e.g. 22.2.23 or 2022.2.23 directly, we should prefix the version with 0. while testing. This doesn't lock us into using calver. One other scheme I could see working is a combination of calver and a "feature flag". I.e. whenever we start using a new typing feature (e.g. TypeAlias), we increment the first version element, while the rest remains a calver. This way, type checkers can clamp the version number appropriately. We can always change to "full" calver later if that turns out to be the best solution, but the reverse is impossible.

We should release a new types-stdlib less frequently than the third-party packages, for example once a week. The latter change fairly infrequently, so the churn isn't too great, but stdlib usually changes multiple times a day. I wouldn't want to release that often.