Type annotations in the standard library

It seems that few (if any) source files in the standard library have type annotations. I am aware that most of these instead reside in stubs in python/typeshed.

My (naive) question: what is the reason for this continued separation? Now that typing support is relatively mature, would it not be simpler/easier to annotate the source files directly? What am I missing here?


Inertia and cost (for an uncertain benefit). It would be a massive effort (and would probably introduce new bugs due to sheer scale).

If we were to do this, type checkers would start checking function bodies in the stdlib, and we’d have to add a lot more changes, besides just merging the annotations, to get those bodies to pass cleanly.

Not all core devs love type annotations.

It might slow down loading stdlib modules. It would certainly slow down static type checkers.

All that said, for brand new stdlib modules I think we could do an experiment. But we’d need a convention to tell type checkers “for this module, look in the stdlib for inline annotations.”


Supplement to this. There is a -OO option to strip docstring, but there is no option to strip annotations.

Until we have an option to strip annotation, or cost of annotation become neglectable, I’m -1 to add annotations to stdlib.


When I developed backports.zoneinfo, I recall thinking that I would put type annotations directly into the Python version of the module (PEP 399), but most users would be actually loading the C version of the module, and I’m not sure if it’s even possible to add type hints to C extensions directly in the file, so I went with using a stub file (which was then mirrored into typeshed).

For Python-only modules inline type hints should be fine, but if you are writing a PEP 399-style C extension (and admittedly very few of these exist right now), it may not make a lot of sense to maintain stubs and inline type hints.

1 Like

Before you do this, please check whether mypy even looks in the stdlib. IIRC it only looks in the typeshed stubs. Inline annotations may still be attractive for other reasons – but you may have to use stubgen (a tool that comes with mypy) to generate a stub and copy that into typeshed.

1 Like

For reference, previous discussions regarding this: