classification
Title: typing module docs: keep text, add subsections
Type: Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, gvanrossum, levkivskyi, python-dev, ramalho, rhettinger
Priority: normal Keywords: patch

Created on 2020-06-14 19:56 by ramalho, last changed 2020-08-12 18:10 by gvanrossum. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 21574 merged python-dev, 2020-07-21 00:55
PR 21843 merged gvanrossum, 2020-08-12 14:52
Messages (12)
msg371514 - (view) Author: Luciano Ramalho (ramalho) * Date: 2020-06-14 19:56
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.
msg371624 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-06-16 08:53
Would you care to submit a PR?
msg371694 - (view) Author: Luciano Ramalho (ramalho) * Date: 2020-06-16 20:05
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!
msg371695 - (view) Author: Luciano Ramalho (ramalho) * Date: 2020-06-16 20:08
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 ...
msg374036 - (view) Author: Luciano Ramalho (ramalho) * Date: 2020-07-20 23:45
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
msg374046 - (view) Author: Luciano Ramalho (ramalho) * Date: 2020-07-21 01:36
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."
msg374050 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-07-21 03:01
This organization makes good sense to me.   Hopefully, we can get Guido and Ivan to take a look at it.
msg374090 - (view) Author: Ivan Levkivskyi (levkivskyi) * (Python committer) Date: 2020-07-22 10:17
FWIW I like Guido's suggestion in the PR, I would rather use "importance order" than alphabetical order.
msg374676 - (view) Author: Luciano Ramalho (ramalho) * Date: 2020-08-02 01:08
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"
msg374700 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-08-02 22:33
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
msg374701 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-08-02 22:34
Thank you so much for your hard work and flexibility! The chapter is in much better shape now.
msg375277 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-08-12 18:10
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
History
Date User Action Args
2020-08-12 18:10:16gvanrossumsetmessages: + msg375277
2020-08-12 14:52:16gvanrossumsetpull_requests: + pull_request20970
2020-08-02 22:34:02gvanrossumsetstatus: open -> closed
resolution: fixed
messages: + msg374701

stage: patch review -> resolved
2020-08-02 22:33:01gvanrossumsetmessages: + msg374700
2020-08-02 01:08:16ramalhosetmessages: + msg374676
2020-07-22 10:17:09levkivskyisetmessages: + msg374090
2020-07-21 03:01:50rhettingersetnosy: + gvanrossum, levkivskyi
messages: + msg374050
2020-07-21 01:36:03ramalhosetmessages: + msg374046
2020-07-21 00:55:15python-devsetkeywords: + patch
nosy: + python-dev

pull_requests: + pull_request20717
stage: patch review
2020-07-20 23:45:01ramalhosetmessages: + msg374036
2020-06-16 20:08:18ramalhosetmessages: + msg371695
2020-06-16 20:05:57ramalhosetmessages: + msg371694
2020-06-16 08:53:43rhettingersetnosy: + rhettinger
messages: + msg371624
2020-06-14 19:56:11ramalhocreate