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.

Sign up for GitHub

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

Jump to bottom

Update Index for set, dict, and generator 'comprehensions' #74167

Closed
terryjreedy opened this issue Apr 4, 2017 · 10 comments
Closed

Update Index for set, dict, and generator 'comprehensions' #74167

terryjreedy opened this issue Apr 4, 2017 · 10 comments
Labels
3.8 only security fixes 3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir easy type-bug An unexpected behavior, bug, or error

Comments

@terryjreedy
Copy link
Member

BPO 29981
Nosy @akuchling, @terryjreedy, @bitdancer, @mlouielu, @miss-islington, @DahlitzFlorian
PRs
  • bpo-29981: Update Index for set, dict, and generator 'comprehensions' #995
  • bpo-29981: Update Index for set, dict, and generator 'comprehensions' #20272
  • [3.9] bpo-29981: Add examples and update index for set, dict, and generator comprehensions'(GH-20272) #22836
  • [3.8] bpo-29981: Add examples and update index for set, dict, and generator comprehensions'(GH-20272) #22837
    		•

    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-10-25.02:57:18.912>
created_at = <Date 2017-04-04.18:01:11.476>
labels = ['easy', 'type-bug', '3.8', '3.9', '3.10', 'docs']
title = "Update Index for set, dict, and generator 'comprehensions'"
updated_at = <Date 2020-10-25.02:57:18.912>
user = 'https://github.com/terryjreedy'

    bugs.python.org fields:

    activity = <Date 2020-10-25.02:57:18.912>
actor = 'methane'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-10-25.02:57:18.912>
closer = 'methane'
components = ['Documentation']
creation = <Date 2017-04-04.18:01:11.476>
creator = 'terry.reedy'
dependencies = []
files = []
hgrepos = []
issue_num = 29981
keywords = ['patch', 'easy']
message_count = 10.0
messages = ['291129', '291132', '296580', '369475', '369489', '369490', '369501', '379165', '379554', '379555']
nosy_count = 7.0
nosy_names = ['akuchling', 'terry.reedy', 'r.david.murray', 'docs@python', 'louielu', 'miss-islington', 'DahlitzFlorian']
pr_nums = ['995', '20272', '22836', '22837']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue29981'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']
    @terryjreedy
    Copy link
    Member Author

    The index currently has

    comprehensions
    *list*

    with *list* linked to 6.2.5 List displays.  I suggest:
    1. Link *comprehensions* to 6.2.4. Displays for lists, sets and dictionaries
    2. Add subentries *set*, *dict*, and *generator* linked to
      2a. 6.2.6. Set displays
      2b. 6.2.7. Dictionary displays
      2c. 6.2.8. Generator expressions

    We don't *call* generator expressions 'generator comprehensions', but that is what they are syntactically and one looking for 'comprehensions' should be able to find them there.

    There is already

    *list*
    ...
    *comprehensions*
    ...
    *list comprehensions*

    with 'list' and 'list comprehensions' linked to glossary entries, while 'list, comprehensions' links to the same section as 'comprehensions, list'.

    1. Add 'set/dictionary, comprehensions' sub-entries linked like 'list, com
    2. Add Glossary entries and links like 'list comprehensions'

    @terryjreedy terryjreedy added the 3.7 (EOL) end of life label Apr 4, 2017
    @terryjreedy terryjreedy added docs Documentation in the Doc dir easy type-bug An unexpected behavior, bug, or error labels Apr 4, 2017
    @terryjreedy
    Copy link
    Member Author

    See bpo-29983 for expanding the title of the 'atoms' section containing subsections on comprehensions.

    @terryjreedy terryjreedy changed the title Update Index set, dict, and generator 'comprehensions' Update Index for set, dict, and generator 'comprehensions' Apr 4, 2017
    @bitdancer
    Copy link
    Member

    On the PR Berker wrote:

    I'm wondering if we should still advertise the use of set([...]). We replaced all instances of it with set literals in the stdlib.

    set([...]) is part of the language, and the python documentation is also a specification of the language, so I think the reference *must* stay.

    @DahlitzFlorian
    Copy link
    Mannequin

    DahlitzFlorian mannequin commented May 20, 2020

    I would like to work on this issue if it is still open.

    @terryjreedy
    Copy link
    Member Author

    The issue is still open. The basic idea is to treat list, set, and dict in parallel fashions in the docs, mostly copying what is done with lists for the other two. In my original post, the title and items 1 to 3 are about index entries in Reference chapter 6, Expressions (reference/expressions.rst). I tacked on item 4 about adding entries to the Glossary (glossary.rst). These could easily be and for easier review should be separate PRs.

    The original PR, opened relatively soon after githup went public, was reviewed by 5 different committers, which is an unusually large number.
    It included both indexing and glossary changes, and added changes to the Library chapter on built-in types (stdtypes.rst). The last was the most controversial and definitely needed to be a followup PR.

    In June 2017, after much discussion and revision, Louie Lu switched his github account from 'louisom' to 'louielu' and ceased working on this. Some later, louisom/cpython was deleted and the PR closed for inactivity.

    We don't *call* generator expressions 'generator comprehensions',

    A subsequent pydev discussion approved of 'generator comprehension' and I believe some doc changes followed*. So I expect that the previous PR is somewhat obsolete. Pick either indexing Expressions or new Glossary entries and see what change you think is still needed and consider any discussion of that change on PR 995. Note: I am not sure that I reviewed (and approved) the index part of the patch, as I likely focused on other parts. You can propose (and justify) changes here before making a PR.

    • Any changes may or may not have been backported to 3.7, so it may or may not be possible to easily backport any new changes (with the robot).

    @terryjreedy terryjreedy added 3.8 only security fixes 3.9 only security fixes 3.10 only security fixes labels May 21, 2020
    @terryjreedy
    Copy link
    Member Author

    I wrote the above before your PR was listed here. I will review it a piece at a time.

    @DahlitzFlorian
    Copy link
    Mannequin

    DahlitzFlorian mannequin commented May 21, 2020

    I guess it would have been good if I waited submitting a PR until you replied to my message. This way, I would have known that two separate PRs would be better suited here - sorry for that.

    Nevertheless, I read the discussions here and in PR #995 and I'm pretty sure that the proposed changes do fit into the documentation (pretty similar to those from PR #995).

    I'm eager to hear your or other people's feedback - thanks!

    @akuchling
    Copy link
    Member

    New changeset 2d55aa9 by Florian Dahlitz in branch 'master':
    bpo-29981: Add examples and update index for set, dict, and generator comprehensions'(GH-20272)
    2d55aa9

    @miss-islington
    Copy link
    Contributor

    New changeset 60bef61 by Miss Skeleton (bot) in branch '3.8':
    bpo-29981: Add examples and update index for set, dict, and generator comprehensions'(GH-20272)
    60bef61

    @miss-islington
    Copy link
    Contributor

    New changeset 2cccc29 by Miss Skeleton (bot) in branch '3.9':
    bpo-29981: Add examples and update index for set, dict, and generator comprehensions'(GH-20272)
    2cccc29

    @methane methane removed the 3.7 (EOL) end of life label Oct 25, 2020
    @methane methane closed this as completed Oct 25, 2020
    @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
    Assignees
    No one assigned
    Labels
    3.8 only security fixes 3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir easy type-bug An unexpected behavior, bug, or error
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    5 participants
    @methane @akuchling @bitdancer @terryjreedy @miss-islington