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.

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.

What about TypedDictFallback?

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

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 😆

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.

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

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.

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.

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.

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?

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.

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.

+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)

Since there were no further comments, I think this is ready for merging.

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