The typing module documentation page has a very long section "Classes, functions, and decorators" (https://docs.python.org/3/library/typing.html#classes-functions-and-decorators) that should be split in subsections. The ordering of the entries seems haphazard: it's not alphabetical. Its grouped according to invisible categories. The categories appear as comments in the source code of typing.py: the `__all__` global lists the API split into categories (see below). We should add these categories to the page as subsections of "Classes, functions, and decorators" - Super-special typing primitives. - ABCs (from collections.abc). - Structural checks, a.k.a. protocols. - Concrete collection types.

Would you care to submit a PR?

Thanks, I am happy to submit a PR. Before I do, I'd like to discuss the subsection titles, starting from the arrangement in typing.__all__: # Special typing constructs (source comment is: "Super-special typing primitives") Any Callable ClassVar Final ForwardRef Generic Literal Optional Protocol Tuple Type TypeVar Union In this section I propose we add: - NamedTuple and TypedDict: source comments say "Not really a type" (for both), and I believe it's confusing to list them along the other collections. Tuple is already in the "Special constructs" category, so NamedTuple should follow in there. TypedDict is very different from the other collections, it's purely a type hinting construct with no runtime counterpart so it's pretty special IMHO. - AnyStr: should be listed right after TypeVar, NoReturn, NewType - Text, TYPE_CHECKING: I am not sure about those, but if they are removed from the "One-off things" all that remains are functions and decorators, which looks good. # ABCs (from collections.abc) [Keep this title] AbstractSet ByteString Container ContextManager Hashable ItemsView Iterable Iterator KeysView Mapping MappingView MutableMapping MutableSequence MutableSet Sequence Sized ValuesView Awaitable AsyncIterator AsyncIterable Coroutine Collection AsyncGenerator AsyncContextManager # Concrete collection types [keep this title] ChainMap Counter Deque Dict DefaultDict List OrderedDict Set FrozenSet - Generator should go with "ABCs" - NamedTuple TypedDict should go with "Special typing constructs" # Protocols (source comment is "Structural checks, a.k.a. protocols.") Reversible SupportsAbs SupportsBytes SupportsComplex SupportsFloat SupportsIndex SupportsInt SupportsRound # Functions and decorators (source comment is "One-off things.") cast final get_args get_origin get_type_hints no_type_check no_type_check_decorator overload runtime_checkable - AnyStr NewType NoReturn: these should go with "Special typing constructs" - Text TYPE_CHECKING: either go with "Special typing constructs" or a constants section, which could include AnyStr as well There are also the IO and re types which could have their own subsections. Looking forward for feeback on this. Thanks!

Sorry, there was an editing mistake above. Where I wrote: - AnyStr: should be listed right after TypeVar, NoReturn, NewType I meant to write: - AnyStr: should be listed right after TypeVar - NoReturn, NewType: both belong with "Special Constructs" as well - Text, TYPE_CHECKING: I am not sure about those ...

This is my proposal for sections to replace the existing "Classes, functions, and decorators" section. The names are sorted within each section. # Special typing primitives	Any	Callable	ClassVar	ForwardRef	Generic	Literal	NamedTuple	NewType	NoReturn	Optional	Type	TypedDict	TypeVar	Union # Generic ABCs	AbstractSet	AsyncContextManager	AsyncGenerator	AsyncIterable	AsyncIterator	Awaitable	ByteString	Collection	Container	ContextManager	Coroutine	Generator	Hashable	io.IO	io.BytesIO	io.TextIO	ItemsView	Iterable	Iterator	KeysView	Mapping	MappingView	MutableMapping	MutableSequence	MutableSet	re.Pattern	re.Match	Sequence	Sized	ValuesView # Generic Concrete Collections	ChainMap	Counter	DefaultDict	Deque	Dict	FrozenSet	List	OrderedDict	Set	Tuple # Structural checks, a.k.a. protocols.	Reversible	SupportsAbs	SupportsBytes	SupportsComplex	SupportsFloat	SupportsInt	SupportsRound # Functions and decorators	cast	final	get_args	get_origin	get_type_hints	no_type_check	no_type_check_decorator	overload	runtime_checkable	type_check_only # Aliases and constants	AnyStr	Text	TYPE_CHECKING

Reviewers, besides adding section titles and reordering the entries, I made only these changes to the text: - entry for IO, TextIO, BinaryIO: added sentence "These types are in the ``typing.io`` namespace." - entry for Pattern, Match: added sentence "These types are in the ``typing.re`` namespace." - entry for TypedDict: removed the words "equivalent to" from the sentence "At runtime it is <equivalent to> a plain dict."

This organization makes good sense to me. Hopefully, we can get Guido and Ivan to take a look at it.

FWIW I like Guido's suggestion in the PR, I would rather use "importance order" than alphabetical order.

I have incorporated Guido's suggestions and added additional subsections to make it easier to navigate the page. I also added notes that fix the issue https://bugs.python.org/issue40978 — "Document that typing.SupportsXXX protocols are runtime checkable"

 New changeset ab72fdeb82c3ab045b480cd4bb4f928c12653ecb by Luciano Ramalho in branch 'master': bpo-40979: refactored typing.rst; (mostly) same content, new sub-sections and ordering (#21574) https://github.com/python/cpython/commit/ab72fdeb82c3ab045b480cd4bb4f928c12653ecb 

Thank you so much for your hard work and flexibility! The chapter is in much better shape now.

 New changeset b3ad2ca56afc6a56c9a6e7b419bc05e8e5b15e19 by Guido van Rossum in branch '3.9': [3.9] bpo-40979: refactored typing.rst; (mostly) same content, new sub-sections and ordering (GH-21574) (#21843) https://github.com/python/cpython/commit/b3ad2ca56afc6a56c9a6e7b419bc05e8e5b15e19