In many of the standard packages located in Lib/ there are little to no type hints. This is not super useful for those using these packages and static type checkers like MyPy. Perhaps I’m unaware of a reason that these packages do not have type hints. If not i’d love to help fix these typing issues that maybe others have had too!
It’s because they are kept externally in GitHub - python/typeshed: Collection of library stubs for Python, with static types .
All the type checkers know about and use typeshed, so it’s not a problem.
3 Likes
Adding the type annotations directly in the code is presumably controversial so probably not a good idea to pursue without some explicit sanction.
3 Likes
bschubert
December 6, 2024, 2:23am
4
Some related past discussions you may find interesting:
At the Core Dev sprint in Bellevue we had a brief discussion about static type annotations in CPython. I want to encapsulate what was discussed and see if the wider core dev community agrees before trying to commit some of this to the devguide.
When static type annotations became a thing, the clear decision was made that they should not, for the time being, go into the standard library. There’s a separate project, typeshed, that provides type annotations for the stdlib instead. This provide…
I’d like us to think carefully about this.
I agree that this might be nice for “simple” type annotations, where an argument can e.g. only be a str or whatever. But I’d be wary of starting a large-scale project to add type hints in lots of places.
As a typeshed maintainer and a codeowner for typing.py, I’m obviously pro-typing. But I’ve also seen how “apparently simple” functions can get very complicated to add annotations for. There will be a lot of functions where we won’t be able to add typ…
opened 12:06PM - 14 May 21 UTC
project: policy
In my opinion, one long term goal should be to integrate the standard library ty… pe hints into the standard library itself. The advantage of having type hints directly in Python are the same advantages as for third-party stubs: tighter coupling and prevention of divergence, better capturing an author's intent, better availability, not needing to maintain multiple versions of stubs.
At this point, this issue is not so much intended as a concrete plan, but for a collection of ideas, thoughts, and challenges. Any concrete plan should take the form of a PEP and be discussed on python-dev.
Here are some of my thoughts.
## Stubs vs. inline type hints
Extension modules will need to use type stubs. An open question here is the relation between the argument clinic and stubs, since they both fulfill the same function to a certain degree, but with different goals. Maybe it's possible to generate stubs automatically?
There is a similar question about using stubs vs inline type hints for Python modules. One advantage of using stubs is consistency with extension modules, and that it gives a bit more flexibility. But what about Python modules using type hints? Maybe it's also possible to use automatic generation using something like my very incomplete [stub-extractor](/srittau/stub-extractor)?
## Incremental Adoption
I believe that it would make sense to introduce type hints slowly to the standard library: Start with modules that already have high quality stubs in typeshed and that are actively maintained in Python, by core developers that are willing to support type hints in the future. This has the advantage of slowly introducing type hints to core developers who didn't have contact with them before, and doesn't force skeptical core developers to use them. It also prevents us from having low-quality type hints in Python, or from deteriorating type hint quality.
The downside of an incremental adoption is confusion of where to find which stub and a higher burden to contribute fixes for non-core developers (but a lower burden for core developers). The latter is also a good reason only to add stubs that are already high quality, since they are less likely to require changes.
## Scope
What should be part of the stubs? Only public API? Or should it be like our typeshed policy where we include non-documented members on request? Should we include docstrings?
## My vision
My vision (at the moment): Use stub files for every module, only include public and semi-public API, and include docstring. This way, we have a clearly defined API, easy access to types and documentation for tools, and an easily accessible and comprehensive reference during development. docs.python.org's documentation could focus more on teaching each module and delegate more of its reference responsibilities to the stub files.
6 Likes