Document _typeshed

[srittau]

This came up in pallets/werkzeug#2130. Maybe it's time we started to document how _typeshed works outside of the file itself. I also think that we should give some API guarantees as people have started to use it outside typeshed itself. Any ideas?

Concerning the latter: I think we should document which aliases etc. are considered stable and we could commit for them to remain stable. To remove or incompatibly change a "stable" alias, we have to remove it from the stable list and mark it deprecated for at least a year.

[JelleZijlstra]

Your ideas sound good. I think it would also be nice to be able to import it without if TYPE_CHECKING. Perhaps we could add the stable parts of _typeshed to typing_extensions, though that would mean a change in purpose for that module.

[srittau]

+1 on typing_extensions. We could also try to add a few aliases to the stdlib. In fact I opened bpo-42012 a while ago, but got not response.

[hauntsaninja]

I think wsgiref.types might be a slightly harder sell for CPython than just including a couple very useful Protocols in typing. But yes, would love to move things into typing_extensions and typing... Using _typeshed in ones own code is hacky and generally bad UX.