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

Jump to bottom

help() on operator precedence has confusing entries "await" "x" and "not" "x" #89556

Closed
m-f-h mannequin opened this issue Oct 6, 2021 · 8 comments
Closed

help() on operator precedence has confusing entries "await" "x" and "not" "x" #89556

m-f-h mannequin opened this issue Oct 6, 2021 · 8 comments
Labels
3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@m-f-h
Copy link
Mannequin

m-f-h mannequin commented Oct 6, 2021

BPO 45393
Nosy @zware, @serhiy-storchaka, @vedgar, @ZackerySpytz, @m-f-h
PRs
  • bpo-45393: help() on operator precedence has misleading entries #31246
    		•

    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 = None
created_at = <Date 2021-10-06.15:33:48.494>
labels = ['3.11', 'type-feature', '3.9', '3.10', 'docs']
title = 'help() on operator precedence has confusing entries "await" "x" and "not" "x"'
updated_at = <Date 2022-02-10.07:54:15.797>
user = 'https://github.com/m-f-h'

    bugs.python.org fields:

    activity = <Date 2022-02-10.07:54:15.797>
actor = 'ZackerySpytz'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-10-06.15:33:48.494>
creator = 'MFH'
dependencies = []
files = []
hgrepos = []
issue_num = 45393
keywords = ['patch']
message_count = 7.0
messages = ['403321', '403338', '403341', '403412', '403428', '403434', '412979']
nosy_count = 6.0
nosy_names = ['docs@python', 'zach.ware', 'serhiy.storchaka', 'veky', 'ZackerySpytz', 'MFH']
pr_nums = ['31246']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue45393'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']
    @m-f-h
    Copy link
    Mannequin Author

    m-f-h mannequin commented Oct 6, 2021

    Nobody seems to have noticed this AFAICS:
    If you type, e.g., help('+') to get help on operator precedence, the fist column gives a lit of operators for each row corresponding to a given precedence. However, the row for "not" (and similar for "await"), has the entry

    "not" "x"

    That looks as if there were two operators, "not" and "x". But the letter x is just an argument to the operator, so it should be:

    "not x"

    exactly as for "+x" and "-x" and "~x" and "x[index]" and "x.attribute", where also x is not part of the operator but an argument.

    On the corresponding web page https://docs.python.org/3/reference/expressions.html#operator-summary
    it is displayed correctly, there are no quotes.

    @m-f-h m-f-h mannequin added 3.7 (EOL) end of life 3.8 only security fixes 3.10 only security fixes 3.11 only security fixes 3.9 only security fixes labels Oct 6, 2021
    @m-f-h m-f-h mannequin assigned docspython Oct 6, 2021
    @m-f-h m-f-h mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement 3.7 (EOL) end of life 3.8 only security fixes 3.10 only security fixes 3.11 only security fixes 3.9 only security fixes labels Oct 6, 2021
    @serhiy-storchaka serhiy-storchaka removed 3.7 (EOL) end of life 3.8 only security fixes labels Oct 6, 2021
    @serhiy-storchaka serhiy-storchaka changed the title help() on operator precedence has confusing entries "avait" "x" and "not" "x" help() on operator precedence has confusing entries "await" "x" and "not" "x" Oct 6, 2021
    @m-f-h
    Copy link
    Mannequin Author

    m-f-h mannequin commented Oct 6, 2021 

    Thanks for fixing the typo, didn't knnow how to do that when I spotted it (I'm new to this). 
You also removed Python version 3.6, 3.7, 3.8, however, I just tested on pythonanywhere,
>>> sys.version
'3.7.0 (default, Aug 22 2018, 20:50:05) \n[GCC 5.4.0 20160609]'
So I can confirm that the bug *is* there on 3.7 (so I put this back in the list - unless it was removed in a later 3.7.x (to you mean that?) and put back in later versions...?)
It is also on the Python 3.9.7 I'm running on my laptop, so I'd greatly be surprised if it were not present on the other two versions you also removed.

    @m-f-h m-f-h mannequin added 3.7 (EOL) end of life 3.8 only security fixes labels Oct 6, 2021
    @vedgar
    Copy link
    Mannequin

    vedgar mannequin commented Oct 7, 2021

    I guess those old versions were removed because they are "frozen", that is, not receiving doc fixes anymore.

    @zware
    Copy link
    Member

    zware commented Oct 7, 2021

    Correct; 3.7 and 3.8 are both in security-fix-only maintenance mode; their documentation is no longer updated unless a security-related fix causes a significant change in behavior that needs to be documented.

    As far as fixing this issue, we have a few options. The cause is that the source for these rows looks like ':keyword:`await` ``x``', which basically produces two inline code blocks with a non-code space between, which the pydoc-topics renderer renders as two separately quoted words.

    Option 1: Replace ':keyword:`await` ``x``' with `:keyword:`await x <await>`. This keeps the link to the `await` anchor, but extends it across the ' x' bit. The pydoc rendering is '"await x"'.

    Option 2: Replace ':keyword:`await` ``x``' with '``await x``. This also gives the pydoc rendering of '"await x"', but loses the link to the `await` anchor, which I would rather not do.

    Option 3: As option 2, but also replace 'Await' in the description column with a link to the await anchor. This breaks from how other keywords in the table are linked.

    Option 4: Adjust the pydoc-topics renderer to smush together consecutive inline code blocks. This might cause some issues elsewhere.

    @zware zware removed 3.7 (EOL) end of life 3.8 only security fixes labels Oct 7, 2021
    @m-f-h
    Copy link
    Mannequin Author

    m-f-h mannequin commented Oct 7, 2021

    option 1 looks most attractive to me (and will also look most attractive in the rendering, IMHO -- certainly better than "await" "x", in any case).

    P.S.: OK, thanks for explanations concerning 3.6 - 3.8. I do understand that it won't be fixed for these versions (not certain why not if possible at no cost), but I do not understand why these labels must be removed. The bug does exist but should simply be considered as "nofix" for these versions (or not), given that it's not in the "security" category. The fact that it won't be fixed, for whatever reason, should not mean that it should not be listed as existing, there.

    @serhiy-storchaka
    Copy link
    Member

    In past we could backport some simple documentation fixes to security-only branches. But currently only the release manager of the corresponded version has permission to commit to these branches, and we do not want to disturb them for such minor cause.

    I concur with analysis of Zachary. All options look good to me.

    @ZackerySpytz
    Copy link
    Mannequin

    ZackerySpytz mannequin commented Feb 10, 2022

    I have created a patch for this issue.

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @ambv
    Copy link
    Contributor

    ambv commented May 19, 2022

    This is now fixed, thanks Zackery!

    @ambv ambv closed this as completed May 19, 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.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    3 participants
    @ambv @serhiy-storchaka @zware