I’ve run afoul of the “annotations as (standardized) documentation” conflicting with “import performance”. In #123429, we added a new private method and included -> Self as the return type, which I included because it provides documentation to the reader of the code as to what’s the intended return type (Alex’s point 2).
Not long after, #128981 removes that documentation and its value in exchange for better import-time performance.
Many code authors (especially LLMs these days) include type annotations by default, so it’s going to become increasingly harder to avoid the introduction of these constructs in the stdlib. This case provides more evidence that we should consider Oscar’s suggestion to enforce the omission of type annotations so at least these issues can be caught earlier.
Long term, especially if we wish to allow more type annotations, we’ll probably need to find a way to performance optimize the import constructs such that using annotations (importing typing) isn’t a significant performance hit.