what is typeshed's approach for libraries that radically change their API across major versions?

[zzzeek]

This is again for SQLAlchemy.

Suppose typeshed releases a set of stubs for a library that's at version 3.0 then the library in question releases version 4.0, it's the same package on pypi, but has major API changes - not just new APIs, but changes to argument signatures, methods removed, etc. Suppose the package releases a stubs setup, and they also update that, so there's mypackage-stubs 3.0, and mypackage-stubs 4.0.

How does typeshed accommodate that? do they just replace the stubs and all users of version 3.0 of the library no longer have accurate stubs in typeshed?

That's the first part of my question. The more difficult part is that SQLAlchemy 2.0 is inlining all of the typing. Meaning, the presence of sqlalchemy-stubs in typeshed at all will break our library for all users of typing tools. We have experimented with various ways of producing a "null-stubs" package, such as blank with just a py.typed file that's "partial", but type checkers in that case still fall back to what's in typeshed, ignoring the annotations in the library itself.

At the moment, it looks like our approach would need to be that we fully generate pyi stubs using a stub generation tool and ship them anyway. typeshed would adopt these once SQLAlchemy 2.0 is fully released. This has many obvious downsides however.

[zzzeek]

cc @CaselIT

[Akuli]

Part 1: We just release stubs for the latest version. If someone is stuck on mypackage version 3.0, they can continue using types-mypackage==3.0.x. Any changes in typeshed will lead to automatically releasing types-mypackage==4.0.x.

Edit: To clarify, if mypackage 4.x comes with type annotations, typeshed will be stuck on 3.x for 6 months or so, and after that, the stubs will be removed from typeshed. After that, they will still be available on pypi.

Part 2: SQLAlchemy 1.x stubs are a mess. There is at least:

• types-sqlalchemy: maintained in typeshed, new, incomplete and mostly auto-generated
• sqlalchemy-stubs: a mypy plugin and related stubs, in dropbox's github: https://github.com/dropbox/sqlalchemy-stubs
• srittau's personal sqlalchemy stubs: https://github.com/srittau/python-stubs

For 2.x, it would be awesome if SQLAlchemy would just come with inline type annotations, and we wouldn't have to deal with any of this. 1.x would still continue working. Typeshed wouldn't accept pull requests that add 2.x features, and we would instead tell people to uninstall types-sqlalchemy. This is what we did when pallet projects (click, flask etc) got inline type annotations, and it worked well.

[zzzeek]

Part 1: We just release stubs for the latest version. If someone is stuck on mypackage version 3.0, they can continue using types-mypackage==3.0.x. Any changes in typeshed will lead to automatically releasing types-mypackage==4.0.x.

right, I see there are packages on pypi for each set of stubs. But most people get their stubs as pre-installed with Mypy, pylance, etc. I guess the idea is that in their environments, they make sure the stubs they want are actually in their Python path / pylance stubs path such that it bypasses the ones that are fixed in those tools, OK.

Edit: To clarify, if mypackage 4.x comes with type annotations, typeshed will be stuck on 3.x for 6 months or so, and after that, the stubs will be removed from typeshed. After that, they will still be available on pypi.

sure, that's fine

Part 2: SQLAlchemy 1.x stubs are a mess. There is at least:

* `types-sqlalchemy`: maintained in typeshed, new, incomplete and mostly auto-generated

* `sqlalchemy-stubs`: a mypy plugin and related stubs, in dropbox's github: https://github.com/dropbox/sqlalchemy-stubs

* srittau's personal sqlalchemy stubs: https://github.com/srittau/python-stubs

This thing is not straightforward to type at all. I have a new approach working for 2.0 that has a few trivial, but of the somewhat global-search-and-replace variety, API usage adjustments that should get most of what's doable with typing right now working without any plugins. A major rationale for 2.0 overall was to reduce implicit behaviors and automations so things would be more amenable to typing.

For 2.x, it would be awesome if SQLAlchemy would just come with inline type annotations, and we wouldn't have to deal with any of this.

that's the plan, I dont want to maintain stubs or plugins at all. this plan is happening right now. im deep into it facing a giant wall of mypy errors to resolve. but then we'll be done save for new typing feature support.

however, when we release 2.0, there wont be a stubs package (as far as what the plan seems to be at the moment). Which means until typeshed drops those stubs also, the tooling, e.g. mypy, pylance, pyright, are going to have hardcoded sqlalchemy 1.x stubs in them, and so far there's no easy way to work around that, you have to dive into the . configuration and search for sqlalchemy stubs and delete them. that's mostly the problem we're looking at, which we would resolve by generating a new sqlalchemy2-stubs that just mirrors what's in the source code.

1.x would still continue working. Typeshed wouldn't accept pull requests that add 2.x features, and we would instead tell people to uninstall types-sqlalchemy. This is what we did when pallet projects (click, flask etc) got inline type annotations, and it worked well.

yup it's just the way the tools hardcode the bundling of typeshed that seems like it needs additional steps.

[hauntsaninja]

mypy stopped bundling typeshed stubs for third party libraries when typeshed switched to the "modular" approach of releasing types-* packages on PyPI.

[srittau]

At least mypy doesn't ship with any third-party stubs anymore. I think pylance/pyright still ships third-party packages, but they are quick to respond to requests. typeshed will add an obsolete-since marker to their stubs, once SQLAlchemy releases with a py.typed file, so that at least a note will be added to the README to point out that the stubs are obsolete. (Also the stubs major version differing from upstream is a hint.)

[zzzeek]

mypy stopped bundling typeshed stubs for third party libraries when typeshed switched to the "modular" approach of releasing types-* packages on PyPI.

ah wasn't sure I realized that, as i have different mypy's all over the place. Yes that seems to be the case now, they aren't bundling, OK that's great.

[zzzeek]

yes I've been in a lot of communication with the pylance folks on this, I had mistakenly thought mypy was also still bundling all of typeshed.

[srittau]

A quick note on the various stubs:

• dropbox/sqlalchemy-stubs seems to be obsolete due to sqlalchemy/sqlalchemy2-stubs.
• sqlalchemy/sqlalchemy2-stubs work in conjunction with a mypy plugin, so it's mostly mypy-specific.
• types-sqlalchemy from typeshed is plugin-agnostic and works with other typecheckers.
• My personal stubs are outdated and will get replaced by types-sqlalchemy, once I've managed to get the types ported over.
• If SQLAlchemy 2 ships with a py.typed file, typeshed's stubs will be dropped.

On a general note, I would recommend to constrain the types dependency similar to how the main dependency is constraint, e.g.:

foo >= 3.2.5, <4
types-foo >= 3.2, <4

This should work for the majority of cases.