Navigation Menu

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

Documentation on GenericAlias objects and __class_getitem__ could be improved #89843

Closed
AlexWaygood opened this issue Oct 30, 2021 · 24 comments
Closed
Labels
3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error

Comments

@AlexWaygood
Copy link
Member

BPO 45680
Nosy @gvanrossum, @ambv, @JelleZijlstra, @miss-islington, @Fidget-Spinner, @AlexWaygood
PRs
  • bpo-45680: Clarify documentation on GenericAlias objects #29335
  • bpo-45680: typing docs: improve links to docs on GenericAlias/__class_getitem__ #29387
  • [doc] bpo-45680: Improve glossary entry for generic types #29388
  • [doc] bpo-45680: Disambiguate __getitem__ and __class_getitem__ in the data model. #29389
  • [3.10] bpo-45680: typing docs: improve links to docs on GenericAlias/__class_getitem__ (GH-29387) #29399
  • [3.9] bpo-45680: typing docs: improve links to docs on GenericAlias/__class_getitem__ (GH-29387) #29400
  • [3.10] [doc] bpo-45680: Improve glossary entry for generic types (GH-29388) #29447
  • [3.9] [doc] bpo-45680: Improve glossary entry for generic types (GH-29388) #29448
  • bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects #29479
  • [3.9] [doc] bpo-45680: Disambiguate __getitem__ and __class_getitem__ in the data model (GH-29389) #29619
  • [3.10] [doc] bpo-45680: Disambiguate __getitem__ and __class_getitem__ in the data model (GH-29389) #29620
  • [3.10] bpo-45680: Clarify documentation on GenericAlias objects (GH-29335) #30688
  • [3.9] bpo-45680: Clarify documentation on GenericAlias objects (GH-29335) #30689
  • bpo-45680: Minor formatting fix in stdtypes.rst #30690
  • [3.10] bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects (GH-29479) #31743
  • [3.9] bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects (GH-29479) #31744
  • 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 2022-03-08.03:59:23.108>
    created_at = <Date 2021-10-30.20:21:29.476>
    labels = ['3.11', 'type-bug', '3.9', '3.10', 'docs']
    title = 'Documentation on `GenericAlias` objects and `__class_getitem__` could be improved'
    updated_at = <Date 2022-03-08.07:55:01.501>
    user = 'https://github.com/AlexWaygood'

    bugs.python.org fields:

    activity = <Date 2022-03-08.07:55:01.501>
    actor = 'AlexWaygood'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2022-03-08.03:59:23.108>
    closer = 'JelleZijlstra'
    components = ['Documentation']
    creation = <Date 2021-10-30.20:21:29.476>
    creator = 'AlexWaygood'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 45680
    keywords = ['patch']
    message_count = 24.0
    messages = ['405384', '405385', '405662', '405664', '405665', '405871', '405876', '405878', '406542', '406557', '406558', '410954', '410956', '410959', '410966', '410967', '410969', '411489', '411490', '414712', '414714', '414718', '414719', '414730']
    nosy_count = 7.0
    nosy_names = ['gvanrossum', 'docs@python', 'lukasz.langa', 'JelleZijlstra', 'miss-islington', 'kj', 'AlexWaygood']
    pr_nums = ['29335', '29387', '29388', '29389', '29399', '29400', '29447', '29448', '29479', '29619', '29620', '30688', '30689', '30690', '31743', '31744']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'behavior'
    url = 'https://bugs.python.org/issue45680'
    versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

    @AlexWaygood
    Copy link
    Member Author

    The documentation on GenericAlias objects implies at multiple points that only container classes can implement __class_getitem__, and goes into very little detail about what it means for a non-container class to be parameterized.

    @AlexWaygood AlexWaygood added 3.9 only security fixes 3.10 only security fixes 3.11 only security fixes labels Oct 30, 2021
    @AlexWaygood AlexWaygood added docs Documentation in the Doc dir 3.9 only security fixes type-bug An unexpected behavior, bug, or error 3.10 only security fixes 3.11 only security fixes labels Oct 30, 2021
    @AlexWaygood AlexWaygood added docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error labels Oct 30, 2021
    @AlexWaygood
    Copy link
    Member Author

    This issue is related, but distinct, to previous issue https://bugs.python.org/issue42280.

    @AlexWaygood AlexWaygood changed the title Documentation on GenericAlias objects could be improved Documentation on GenericAlias objects and __class_getitem__ could be improved Nov 3, 2021
    @AlexWaygood AlexWaygood changed the title Documentation on GenericAlias objects could be improved Documentation on GenericAlias objects and __class_getitem__ could be improved Nov 3, 2021
    @Fidget-Spinner
    Copy link
    Member

    New changeset e03e503 by Alex Waygood in branch 'main':
    bpo-45680: typing docs: improve links to docs on GenericAlias/__class_getitem__ (GH-29387)
    e03e503

    @miss-islington
    Copy link
    Contributor

    New changeset c108966 by Miss Islington (bot) in branch '3.10':
    bpo-45680: typing docs: improve links to docs on GenericAlias/__class_getitem__ (GH-29387)
    c108966

    @miss-islington
    Copy link
    Contributor

    New changeset e813dd4 by Miss Islington (bot) in branch '3.9':
    bpo-45680: typing docs: improve links to docs on GenericAlias/__class_getitem__ (GH-29387)
    e813dd4

    @ambv
    Copy link
    Contributor

    ambv commented Nov 6, 2021

    New changeset 77a2c77 by Alex Waygood in branch 'main':
    [doc] bpo-45680: Improve glossary entry for generic types (GH-29388)
    77a2c77

    @ambv
    Copy link
    Contributor

    ambv commented Nov 6, 2021

    New changeset 494f8da by Miss Islington (bot) in branch '3.10':
    [doc] bpo-45680: Improve glossary entry for generic types (GH-29388) (GH-29447)
    494f8da

    @ambv
    Copy link
    Contributor

    ambv commented Nov 6, 2021

    New changeset 643f50c by Miss Islington (bot) in branch '3.9':
    [doc] bpo-45680: Improve glossary entry for generic types (GH-29388) (GH-29448)
    643f50c

    @ambv
    Copy link
    Contributor

    ambv commented Nov 18, 2021

    New changeset 31b3a70 by Alex Waygood in branch 'main':
    [doc] bpo-45680: Disambiguate __getitem__ and __class_getitem__ in the data model (GH-29389)
    31b3a70

    @ambv
    Copy link
    Contributor

    ambv commented Nov 18, 2021

    New changeset fde9f61 by Miss Islington (bot) in branch '3.10':
    [3.10] [doc] bpo-45680: Disambiguate __getitem__ and __class_getitem__ in the data model (GH-29389) (GH-29620)
    fde9f61

    @ambv
    Copy link
    Contributor

    ambv commented Nov 18, 2021

    New changeset 591bf41 by Miss Islington (bot) in branch '3.9':
    [3.9] [doc] bpo-45680: Disambiguate __getitem__ and __class_getitem__ in the data model (GH-29389) (GH-29619)
    591bf41

    @Fidget-Spinner
    Copy link
    Member

    New changeset 0eae9a2 by Alex Waygood in branch 'main':
    bpo-45680: Clarify documentation on GenericAlias objects (GH-29335)
    0eae9a2

    @miss-islington
    Copy link
    Contributor

    New changeset 24d0b33 by Miss Islington (bot) in branch '3.10':
    [3.10] bpo-45680: Clarify documentation on GenericAlias objects (GH-29335) (GH-30688)
    24d0b33

    @Fidget-Spinner
    Copy link
    Member

    New changeset 1faf7c4 by Ken Jin in branch 'main':
    bpo-45680: Minor formatting fix in stdtypes.rst (GH-30690)
    1faf7c4

    @Fidget-Spinner
    Copy link
    Member

    New changeset 0064516 by Ken Jin in branch '3.9':
    [3.9] bpo-45680: Clarify documentation on GenericAlias objects (GH-29335) (GH-30689)
    0064516

    @Fidget-Spinner
    Copy link
    Member

    Phew, we're finally done. Thanks Alex for the PRs, and Łukasz, Guido (and many others) for all the reviews!

    @AlexWaygood
    Copy link
    Member Author

    Wait... there's still PR 29479 open!

    But that can wait a little while -- getting PR 29335 over the line is definitely worth celebrating!!

    @Fidget-Spinner
    Copy link
    Member

    Wait... there's still PR 29479 open!

    Sorry, I was too excited when PR 29335 merged and missed that. In the future, please re-open if you feel I closed an issue wrongly. Thanks!

    @AlexWaygood
    Copy link
    Member Author

    Sorry, I was too excited when PR 29335 merged and missed that. In the future, please re-open if you feel I closed an issue wrongly. Thanks!

    No worries — will do!

    @JelleZijlstra
    Copy link
    Member

    New changeset 5073129 by Alex Waygood in branch 'main':
    bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects (GH-29479)
    5073129

    @JelleZijlstra
    Copy link
    Member

    And now I think we're really done! Thanks for all your work here @AlexWaygood.

    @miss-islington
    Copy link
    Contributor

    New changeset 06108c0 by Miss Islington (bot) in branch '3.10':
    bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects (GH-29479)
    06108c0

    @miss-islington
    Copy link
    Contributor

    New changeset e83f084 by Miss Islington (bot) in branch '3.9':
    bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects (GH-29479)
    e83f084

    @AlexWaygood
    Copy link
    Member Author

    Thanks so much to Ken, Łukasz, Jelle, Guido, and everybody else who helped review these PRs!

    @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.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error
    Projects
    None yet
    Development

    No branches or pull requests

    5 participants