Type annotations in the stdlib

[EpicWink (Laurie O)]

In general, having a third-party substitute (typeshed) for a first-party feature (typing) of first-party modules (the standard library) doesn’t feel cohesive and adds to a sense of jankiness.

Not confusing readers is certainly something to strive for, but considering that those readers are now likely to be more developers, I don’t think it takes high priority.

I think type-annotating the standard library is something to which will bring further benefits (such as better documentation for std-lib developers and readers), and is therefore worthwhile.

@AlexWaygood

it might be pretty confusing for some people to see that some functions in a certain file are fully annotated whereas others have no annotations at all.

I think it makes sense to have that as a repeat blocker: if any module attributes are annotated, then all must be. I don’t think it should be a blocker on starting to annotate.

@AlexWaygood

Until the stdlib has “type annotation coverage” matching typeshed, type checkers will also have to continue using the typeshed stubs for type-checking user code; they’ll essentially ignore any type hints in the runtime stdlib. That might be highly confusing for end users, if the annotations in the stdlib and the annotations in typeshed diverge for some reason. We’d have to think carefully about how to keep the annotations in the two repos in sync (unless the long-term goal is to get rid of the stdlib stubs from typeshed altogether).

I don’t think it makes sense to keep the stubs in typeshed. We can just *-import after the Python release:

import sys as _sys
import typing as _typing

if _sys.version_info < (3, 12):
     ...  # original stubs
else:
    if _typing.TYPE_CHECKING:
        from mod import *