Copy typechecker-internal symbols to _typeshed._type_checker_internals

[srittau]

Cf. #7580

---

Marked as draft until at least 2025-11-22. Current changes:

• builtins.function: No changes for now, will be removed soon in favor of types.FunctionType
• builtins.ellipsis: No changes for now, will be removed after support for Python 3.9 is dropped in favor of types.EllipsisType
• typing._promote → _typeshed._tc.promote
• typing._TypedDict → _typeshed._tc.TypedDictFallback
• typing.AwaitableGenerator → _typeshed._tc.AwaitableGenerator
• typing.NamedTuple → _typeshed._tc.NamedTupleFallback

[srittau]

Also, considering that this module itself is private, we should use consistent naming. I suggest to also add promote and TypedDict as preferred aliases. We can keep the underscore-prefixed versions if it eases transitions for type checkers.

[AlexWaygood]

What about TypedDictFallback? The class does not aim to provide a stub for the actual TypedDict object at runtime; it provides a set of methods and ClassVars that type checkers should synthesize for all types created using the TypedDict factory function.

[srittau]

What about TypedDictFallback?

I'm not sure what would work best for type checkers. Avoiding a name conflict would be great, of course.

[AlexWaygood]

For red-knot, I would prefer an unambiguous name such as TypedDictFallback. But red-knot has the luxury that we have not yet implemented support for TypedDicts at all yet, so we don't have a large amount of code to update to the new name 😆

[srittau]

I've converted this PR to a draft for at least a week to give us a chance to discuss it. I've also updated it to reflect the current consensus, which I've also listed in the initial comment on this PR.

[Avasam]

Is it worth using the @deprecated decorator on classes you commented as # Obsolete ?
Similarly, class ellipsis could maybe use a @deprecated if you plan a removal after Python 3.9 goes EOL.

typing._TypedDict is duplicated and referenced in a comment in stdlib/typing_extensions.pyi and stubs/mypy-extensions/mypy_extensions.pyi. Those should likely be updated as well.

typing.NamedTuple as a class is referenced in a comment in stubs/tensorflow/tensorflow/python/feature_column/feature_column_v2.pyi

[JelleZijlstra]

I don't think @deprecated would work well here; the intended audience for the deprecation is type checker authors, not end users. We don't want users to see a mypy message every time they use a function.

[Akuli]

Could we name the module more descriptively? Something like _typeshed._type_checker_specific? I don't really see a reason for the name to be short.

[srittau]

Could we name the module more descriptively? Something like _typeshed._type_checker_specific? I don't really see a reason for the name to be short.

I don't like overly long module names, but I've gone with _tc_internals for now.

[Akuli]

I'm not super happy with _tc_internals. We will probably get questions asking what tc in the file name means, which means that many people will be confused by what it is. (Only a fraction of them will ask a question here.)

While I agree about module names in general because they need to be typed many times, I don't think it applies here. Can you give a concrete reason why this shouldn't be _type_checker_internals?

[srittau]

We will probably get questions asking what tc in the file name means, which means that many people will be confused by what it is.

I honestly doubt that as there is a comment at the very top of the file explaining it. I don't remember any questions about other modules here, either.

Can you give a concrete reason why this shouldn't be _type_checker_internals?

I prefer module names to be short and succinct to match the general Python style. For example, looking at stdlib here, long module names are rare – and usually names for C implementations of existing features. Longer names also tend to stand out more in directory listings – something we want to avoid in this case – and make directory listings longer as they force less columns. Finally, longer names cause longer error messages. Frankly, I don't see much reason for a longer name for such a specialized feature as this.

[Akuli]

I still think a longer name would be better, but I'm fine with using a short name because of a comment.

---

There has been confusion about _typeshed (#5201), a module with a reasonably long name.

I think this would benefit from a long file name because it is so special. If someone stumbles into this file, a good name immediately explains what the thing is, while a name that includes tc abbreviation will only cause more confusion, because the tc abbreviation is not really used anywhere else.

[Avasam]

+1 what Akuli said.

My 2 cents: In a day and age where horizontal space isn't sparse, I prefer clear names over potentially vague abbreviations.

The more clearly the name says (whilst staying somewhat concise) "this is internal implementation detail, don't use this" to end-users and library maintainers, the better.

_type_checker_internals doesn't feel exaggeratedly long, and I feel ok having type-checkers use this full name. (granted I don't maintain any type checkers, so w/e my opinion is worth there ^^")

But I also won't die on this hill if _tc_internals is chosen (at least it has "internals" in the name and is private)

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉