Repository navigation
Remove type checker-specific symbols from builtins.pyi and typing.pyi #7580
Description
Activity
contains some insight into why
builtins.functionandtypes.FunctionTypeused to be different.But changes that we made to
builtins.functionin typeshed (to reduce false-positives) mean that they're not so different anymore, e.g.:Reacted by Jelle Zijlstra- added a commit that references this issue
on Apr 11, 2025 #13816 is a first step towards solving it, by making the symbols available in the module
_typeshed._tc. We can then ask type checker authors to switch to that new module and remove the symbols from the wrong places at some later time.I've left out
builtins.ellipsis, since it can be replaced bytypes.EllipsisTypeafter support for Python 3.9 is dropped. (Added as to do item to #13782).For reference, I've linked this issue and the PR on discuss.python.org: https://discuss.python.org/t/removing-type-checker-internals-from-typeshed/87960
Reacted by Alex WaygoodThanks for doing this work. Transitioning to the new types will be a little tricky to coordinate between typeshed and all the type checkers. Would it make sense to provide aliases in
typing.pyithat shadow (i.e. import and re-export) the new type definitions in_typeshed.pyifor a period of time? You could set expectations that they're going away completely in, say, six months. That would help give type checker maintainers a chance to make the required changes without a hard cut-over. It would also ease the transition for users who download their own versions of typeshed rather than using the version that's bundled with their type checker.Would it make sense to provide aliases in
typing.pyithat shadow (i.e. import and re-export) the new type definitions in_typeshed.pyifor a period of time?The idea is to keep the existing definitions for the time being, and only remove them when we're reasonably sure that type checkers have adopted the new names.
Reacted by Eric TrautInstead of adding
_typeshed._tc, should we instead encourage type checkers to stop relying on typeshed for these completely?Looking at the current PR:
promoteis something mypy-specific, it should ideally be removed from typeshed completelyAwaitableGeneratoris mypy implementation details for a mostly obsolete feature. Do other type checkers use this?TypedDictFallbackandNamedTupleFallbackare potentially useful for others (and it appears at least pyright uses them), but the comments for TypedDictFallback are full of discussion about how the signature must be a certain way for the mypy plugin to work correctly. So wouldn't it be better for mypy to host those stubs?
(Also I removed my assignment; I intended to work on this a few years ago but never had the time, sorry!)
AwaitableGeneratoris mypy implementation details for a mostly obsolete feature. Do other type checkers use this?According to @erictraut in python/mypy#8240 (comment), pyright uses it (but that was three years ago!)
4 remaining items
What are regular users supposed to use instead of NamedTuple? Surely it’s not being deprecated? (When we did List -> list, we explicitly said we wouldn’t deprecate List etc.
The comment inline says
# Obsolete, will be changed to a function. Use _typeshed._type_checker_internals.NamedTupleFallback instead.. So we'll maketyping.NamedTuplea function and type checkers should useNamedTupleFallbackfor discovering attributes onNamedTuple.Reacted by Sebastian Rittau, Alex Waygood and Guido van RossumDefinitely this shouldn't change anything about how end users write NamedTuple classes.
Reacted by Alex Waygood and Guido van RossumSo we'll make
typing.NamedTuplea function...I don't understand how a function would work for named tuple class declarations like this:
class MyDataClass(NamedTuple): entry_1: str entry_2: int
I think
typing.NamedTupleneeds to remain a class.I think
typing.NamedTupleneeds to remain a class.@erictraut, I responded at https://discuss.python.org/t/removing-type-checker-internals-from-typeshed/87960/4, since you posted a longer comment there
- added 4 commits that reference this issue
on Nov 1, 2025 I've opened experimental PRs for the removals (but not the
NamedTuplechange to function yet):- Remove builtins.function #14957: mypy still requires it.
- Remove typing._promote #14958: This actually successfully passed our CI and can be removed.
- Remove typing.AwaitableGenerator #14959: CI passes, but mypy_primer crashes.
- Remove typing._TypedDict #14960: There are still problems with pyright (pyright still depends on typing._TypedDict microsoft/pyright#11081) and mypy_primer crashes.
- added a commit that references this issue
on Nov 3, 2025 Spent ten minutes looking at builtins.function in mypy, it's not trivial to fix. Easy to make it work with
builtins._function, in case that's of any use@hauntsaninja Would adding it to
_typeshed._type_checker_internalswork as well?I could probably get that to work for
_TypedDictandAwaitableGenerator, butbuiltins.functionseems much more fundamental(I got it almost working, in that mypy doesn't crash, but stops being able to see things like
__name__etc. I'll look at it with fresh eyes in the morning and see if there's an obvious fix)Reacted by Sebastian RittauI could probably get that to work for
_TypedDictandAwaitableGenerator, butbuiltins.functionseems much more fundamental(I got it almost working, in that mypy doesn't crash, but stops being able to see things like
__name__etc. I'll look at it with fresh eyes in the morning and see if there's an obvious fix)@hauntsaninja I just removed
builitns.ellipsisin python/mypy#21911. Do you think you will have time to continue your work onbuiltins.function? If not and if you can share your progress, I can try to continue what you started.
I'm working to get rid of the type checker-specific symbols that currently are in our core stubs but don't exist at runtime. I'll use this issue to track the work needed. This involves changes both to typeshed and to type checkers.
Affected names:
typing._TypedDict. Suggesting to rename to_typeshed.TypedDictFallback. (mypy and pyright)typing._promote->_typeshed._promote(mypy only)typing.AwaitableGenerator->_typeshed.AwaitableGenerator(mypy and pyright)builtins.function(mypy and pyright). Need to look more into why we can't just usetypes.FunctionType.builtins.ellipsis(mypy and pyright). Should add a new name to _typeshed, similar toNoneType.builtins.modulewas also mentioned in the past but it's been fixed already (mypy PR: python/mypy#3107).Linked issues and PRs:
functionfrom builtins #2999ellipsistype mypy#11564_typeshed._type_checker_internalshas now been added and I've announced it at https://discuss.python.org/t/removing-type-checker-internals-from-typeshed/87960/2. I suggest we wait for a few months and then start removing symbols one by one to judge the fallout. Current list:builtins.ellipsis#15712builtins.function#14957typing._promote#14958typing.AwaitableGenerator#14959typing.NamedTupletyping._TypedDict#14960