Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

typing module docs: keep text, add subsections #85151

Closed
ramalho mannequin opened this issue Jun 14, 2020 · 12 comments
Closed

typing module docs: keep text, add subsections #85151

ramalho mannequin opened this issue Jun 14, 2020 · 12 comments
Labels
3.8 only security fixes 3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir

Comments

@ramalho
Copy link
Mannequin

ramalho mannequin commented Jun 14, 2020

BPO 40979
Nosy @gvanrossum, @rhettinger, @ilevkivskyi, @ramalho
PRs
  • bpo-40979: refactored typing.rst; same content, new sub-sections and ordering #21574
  • [3.9] bpo-40979: refactored typing.rst; (mostly) same content, new sub-sections and ordering (GH-21574) #21843
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = <Date 2020-08-02.22:34:02.504>
    created_at = <Date 2020-06-14.19:56:11.086>
    labels = ['3.8', '3.9', '3.10', 'docs']
    title = 'typing module docs: keep text, add subsections'
    updated_at = <Date 2020-08-12.18:10:16.448>
    user = 'https://github.com/ramalho'

    bugs.python.org fields:

    activity = <Date 2020-08-12.18:10:16.448>
    actor = 'gvanrossum'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2020-08-02.22:34:02.504>
    closer = 'gvanrossum'
    components = ['Documentation']
    creation = <Date 2020-06-14.19:56:11.086>
    creator = 'ramalho'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 40979
    keywords = ['patch']
    message_count = 12.0
    messages = ['371514', '371624', '371694', '371695', '374036', '374046', '374050', '374090', '374676', '374700', '374701', '375277']
    nosy_count = 6.0
    nosy_names = ['gvanrossum', 'rhettinger', 'docs@python', 'python-dev', 'levkivskyi', 'ramalho']
    pr_nums = ['21574', '21843']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = None
    url = 'https://bugs.python.org/issue40979'
    versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

    @ramalho
    Copy link
    Mannequin Author

    ramalho mannequin commented Jun 14, 2020

    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.

    @ramalho ramalho mannequin added 3.8 only security fixes 3.9 only security fixes 3.10 only security fixes labels Jun 14, 2020
    @ramalho ramalho mannequin assigned docspython Jun 14, 2020
    @ramalho ramalho mannequin added 3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir labels Jun 14, 2020
    @ramalho ramalho mannequin assigned docspython Jun 14, 2020
    @ramalho ramalho mannequin added the docs Documentation in the Doc dir label Jun 14, 2020
    @rhettinger
    Copy link
    Contributor

    Would you care to submit a PR?

    @ramalho
    Copy link
    Mannequin Author

    ramalho mannequin commented Jun 16, 2020

    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!

    @ramalho
    Copy link
    Mannequin Author

    ramalho mannequin commented Jun 16, 2020

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

    @ramalho
    Copy link
    Mannequin Author

    ramalho mannequin commented Jul 20, 2020

    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

    @ramalho
    Copy link
    Mannequin Author

    ramalho mannequin commented Jul 21, 2020

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

    @rhettinger
    Copy link
    Contributor

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

    @ilevkivskyi
    Copy link
    Member

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

    @ramalho
    Copy link
    Mannequin Author

    ramalho mannequin commented Aug 2, 2020

    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"

    @gvanrossum
    Copy link
    Member

    New changeset ab72fde by Luciano Ramalho in branch 'master':
    bpo-40979: refactored typing.rst; (mostly) same content, new sub-sections and ordering (bpo-21574)
    ab72fde

    @gvanrossum
    Copy link
    Member

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

    @gvanrossum
    Copy link
    Member

    New changeset b3ad2ca 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) (bpo-21843)
    b3ad2ca

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.8 only security fixes 3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir
    Projects
    None yet
    Development

    No branches or pull requests

    3 participants