Improve type hints in Lib packages

bschubert · December 6, 2024, 2:23am

Some related past discussions you may find interesting:

Thoughts about type hints in the standard library

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.