As a user of VS Code, the autocompletion and informational pop-ups are often very nice. But they can be utterly terrible when type annotations are complicated. As an example, the popup for divmod says:
(__x: SupportsDivMod[_T_contra@divmod, _T_co@divmod], __y: _T_contra@divmod, /) -> _T_co@divmod
While that information may be easy to get (from type annotations) it’s frankly worse than useless as actual documentation. In contrast, help(divmod) gives:
divmod(x, y, /)
Return the tuple (x//y, x%y). Invariant: div*y + mod == x.
I’m not entirely sure what conclusions to draw from this. But it very much feels like the pressure to “use type annotations” has resulted in a badly degraded user experience. Yes, it may well be harder to use and interpret the help() output. But surely user experience should be key here, not ease of implementation?
I’m not trying to complain about VS Code here, or even moan about unreadable type annotations. What I am trying to say is that the community’s enthusiasm for type annotations (and more specifically, certain types of evangelisation for the feature that goes on) is resulting in tools making bad choices in terms of their actual goals. And that leads to a vicous circle, where we have things like the proposal to add documentation to a parameter’s type, “so that tools can access that documentation”.
I think I agree with this, but for me the “fence” is very much a social one, rather than a technical one. We need to make not having type annotations socially acceptable again, and encourage tools to treat code that chooses not to include annotations as just as valid as annotated code. And we need to accept that type annotations are not necessarily readable or useful to the human reader (see the divmod example above) and promote non-typing solutions that are readable.
That’s a slightly different case. Once you have a fully annotated codebase, with strong trust in the results[1] then I can see that leaning on the type annotations would make maintenance easier. But getting to that point is hard (annotating pip is still a work in progress, and pip doesn’t even have a public API, so we don’t have to worry about things like over-restrictive types in the public API) and it’s not obvious to me that the sort of benefits you suggest will arise, particularly if the project already has a good test suite (pip’s test suite sucks - otherwise I could easily imagine the issues you caught with the type checker being caught by unit tests).
Maybe. But that still requires the project maintainer to make a decision as to whether they want type annotations or not. Whereas my personal position is more along the lines of “I’ll add types when I feel comfortable doing so, and I don’t want people trying to rush me in that decision”.
So that’s the real answer here. Instead of people coming along asking me to annotate my library, why aren’t they using that mechanism? “Write your own stubs” should surely be the natural way of interfacing with an untyped library, not “bug the maintainer to add types”.
I don’t want to come across as over-critical here, as I know type annotations solve a lot of problems for a lot of people, and there’s been a huge amount of work put into them, but it’s discussions like this which leave me with the feeling that things are a huge mess unless you are willing to go full-in and annotate everything. Which is why I’m advocating for a much stronger focus on the “typing is optional” idea, making the experience for people who are hostile, skeptical, or even just cautious[2], towards type annotations less negative.