Remove type checker-specific symbols from builtins.pyi and typing.pyi

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 use types.FunctionType.
- Working on this in mypy but it requires updating a ton of test cases
builtins.ellipsis (mypy and pyright). Should add a new name to _typeshed, similar to NoneType.

builtins.module was also mentioned in the past but it's been fixed already (mypy PR: python/mypy#3107).

Linked issues and PRs:

_typeshed._type_checker_internals has 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:

Callable has no attribute __kwdefaults__ mypy#5958

contains some insight into why builtins.function and types.FunctionType used to be different.

But changes that we made to builtins.function in typeshed (to reduce false-positives) mean that they're not so different anymore, e.g.:

Add missing function attributes to builtins.function #6804

Copy typechecker-internal symbols to `_typeshed._tc`

#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 by types.EllipsisType after 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

See the initial comment of #13816 for the current proposal. I'll try to keep it updated according to the consensus of the discussion.

Thanks 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.pyi that shadow (i.e. import and re-export) the new type definitions in _typeshed.pyi for 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.pyi that shadow (i.e. import and re-export) the new type definitions in _typeshed.pyi for 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.

Instead of adding _typeshed._tc, should we instead encourage type checkers to stop relying on typeshed for these completely?

Looking at the current PR:

promote is something mypy-specific, it should ideally be removed from typeshed completely
AwaitableGenerator is mypy implementation details for a mostly obsolete feature. Do other type checkers use this?
TypedDictFallback and NamedTupleFallback are 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!)

@erictraut

AwaitableGenerator is 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!)

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 make typing.NamedTuple a function and type checkers should use NamedTupleFallback for discovering attributes on NamedTuple.

Definitely this shouldn't change anything about how end users write NamedTuple classes.

So we'll make typing.NamedTuple a 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.NamedTuple needs to remain a class.

@erictraut

I think typing.NamedTuple needs 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

Remove builtins.function

Remove typing._promote

Remove typing.AwaitableGenerator

Remove typing._TypedDict

I've opened experimental PRs for the removals (but not the NamedTuple change 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.

Remove typing._promote (#14958)

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

@hauntsaninja Would adding it to _typeshed._type_checker_internals work as well?

I could probably get that to work for _TypedDict and AwaitableGenerator, but builtins.function seems 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 could probably get that to work for _TypedDict and AwaitableGenerator, but builtins.function seems 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.ellipsis in python/mypy#21911. Do you think you will have time to continue your work on builtins.function? If not and if you can share your progress, I can try to continue what you started.

Navigation Menu

Repository navigation

Remove type checker-specific symbols from builtins.pyi and typing.pyi #7580

4 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Remove type checker-specific symbols from builtins.pyi and typing.pyi #7580

Description

Activity

AlexWaygood commented on Apr 3, 2022

srittau commented on Apr 11, 2025

srittau commented on Apr 11, 2025

srittau commented on Apr 11, 2025

erictraut commented on Apr 11, 2025

srittau commented on Apr 11, 2025

JelleZijlstra commented on Apr 11, 2025

AlexWaygood commented on Apr 11, 2025

4 remaining items

gvanrossum commented on May 12, 2025

JelleZijlstra commented on May 12, 2025

JelleZijlstra commented on May 12, 2025

erictraut commented on May 17, 2025

AlexWaygood commented on May 17, 2025

srittau commented on Nov 1, 2025

hauntsaninja commented on Nov 3, 2025

srittau commented on Nov 3, 2025

hauntsaninja commented on Nov 3, 2025

hamdanal commented on Aug 29, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions