[issue40979] typing module docs: keep text, add subsections

[Guido van Rossum]

Guido van Rossum  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[Guido van Rossum]

Change by Guido van Rossum :


--
pull_requests: +20970
pull_request: https://github.com/python/cpython/pull/21843

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[Guido van Rossum]

Guido van Rossum  added the comment:

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

--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[Guido van Rossum]

Guido van Rossum  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[Luciano Ramalho]

Luciano Ramalho  added the comment:

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"

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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

--
nosy: +gvanrossum, levkivskyi

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[Luciano Ramalho]

Luciano Ramalho  added the comment:

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  a plain dict."

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[Roundup Robot]

Change by Roundup Robot :


--
keywords: +patch
nosy: +python-dev
nosy_count: 3.0 -> 4.0
pull_requests: +20717
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/21574

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[ramalho]

ramalho  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[ramalho]

ramalho  added the comment:

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 ...

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[ramalho]

ramalho  added the comment:

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!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[Raymond Hettinger]

Raymond Hettinger  added the comment:

Would you care to submit a PR?

--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40979] typing module docs: keep text, add subsections

[ramalho]

New submission from ramalho :

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.

--
assignee: docs@python
components: Documentation
messages: 371514
nosy: docs@python, ramalho
priority: normal
severity: normal
status: open
title: typing module docs: keep text, add subsections
versions: Python 3.10, Python 3.8, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com