This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: help() on operator precedence has confusing entries "await" "x" and "not" "x"
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: MFH, ZackerySpytz, docs@python, serhiy.storchaka, veky, zach.ware
Priority: normal Keywords: patch

Created on 2021-10-06 15:33 by MFH, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 31246 open ZackerySpytz, 2022-02-10 07:48
Messages (7)
msg403321 - (view) Author: Max (MFH) Date: 2021-10-06 15:33
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.
msg403338 - (view) Author: Max (MFH) Date: 2021-10-06 20:49
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.
msg403341 - (view) Author: Vedran Čačić (veky) * Date: 2021-10-07 00:13
I guess those old versions were removed because they are "frozen", that is, not receiving doc fixes anymore.
msg403412 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2021-10-07 14:00
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.
msg403428 - (view) Author: Max (MFH) Date: 2021-10-07 18:15
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.
msg403434 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2021-10-07 19:08
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.
msg412979 - (view) Author: Zackery Spytz (ZackerySpytz) * (Python triager) Date: 2022-02-10 07:54
I have created a patch for this issue.
History
Date User Action Args
2022-04-11 14:59:50adminsetgithub: 89556
2022-02-10 07:54:15ZackerySpytzsetmessages: + msg412979
2022-02-10 07:48:39ZackerySpytzsetkeywords: + patch
nosy: + ZackerySpytz

pull_requests: + pull_request29415
stage: patch review
2021-10-07 19:08:59serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg403434
2021-10-07 18:15:14MFHsetmessages: + msg403428
2021-10-07 14:00:00zach.waresetnosy: + zach.ware

messages: + msg403412
versions: - Python 3.7, Python 3.8
2021-10-07 00:13:27vekysetnosy: + veky
messages: + msg403341
2021-10-06 20:49:43MFHsetmessages: + msg403338
versions: + Python 3.7, Python 3.8
2021-10-06 15:41:31serhiy.storchakasettitle: help() on operator precedence has confusing entries "avait" "x" and "not" "x" -> help() on operator precedence has confusing entries "await" "x" and "not" "x"
versions: - Python 3.6, Python 3.7, Python 3.8
2021-10-06 15:33:48MFHcreate