classification
Title: Numeric operator predecence confusing
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Mariatta, docs@python, edmundselliot@gmail.com, ezio.melotti, fossilet, jcea, ktt3ja, mdk, meador.inge, miss-islington, ronron
Priority: normal Keywords: easy, patch

Created on 2012-11-08 14:19 by fossilet, last changed 2019-09-11 10:41 by mdk. This issue is now closed.

Files
File name Uploaded Description Edit
16438.patch ktt3ja, 2012-11-22 21:33 review
Pull Requests
URL Status Linked Edit
PR 10521 merged anjalimalik, 2018-11-13 19:40
PR 15904 merged miss-islington, 2019-09-11 09:58
PR 15905 merged miss-islington, 2019-09-11 09:58
Messages (16)
msg175163 - (view) Author: Yongzhi Pan (fossilet) * Date: 2012-11-08 14:19
http://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex

"All numeric types (except complex) support the following operations, sorted by ascending priority."

It list '-' after '+', '/' after '*'. That is to mean '-' has higher precedence than '+'. That is wrong, and is contradicting with here:

http://docs.python.org/3/reference/expressions.html#summary

This should be made clear.
msg175168 - (view) Author: Jesús Cea Avión (jcea) * (Python committer) Date: 2012-11-08 14:27
Precedence ordered per row. Same row, same precedence. I don't see any problem. It is natural math precedence. Closed as invalid.
msg175172 - (view) Author: Yongzhi Pan (fossilet) * Date: 2012-11-08 15:18
I mean the text at the first link need fix. '+' and '-' are not on the same row. And the doc says: "sorted by ascending priority", that means they have ascending priority.

The table in the reference is just right.
msg175178 - (view) Author: Jesús Cea Avión (jcea) * (Python committer) Date: 2012-11-08 15:29
You are right, Yongzhi Pan. Reopening. Not sure how to solve it. Delegating to docs@python.
msg176088 - (view) Author: Kiet Tran (ktt3ja) Date: 2012-11-22 02:08
I was trying to fix this, but I ran into a couple questions.

1) Once I put, say, "x + y" and "x - y" into the same table cell, what would a good format be? My preferred format is to have them on separate lines in the cell, but after a lot of googling on the syntax of reST (and trials and errors), I'm still unable to figure out how to do it. Using bullet points would mean I have to align elements in the "Notes" column with the ones in the "Operation" column somehow. Alternatively, I can separate them by comma, but the table would look a bit cluttered.

2) Should the functions abs, int, etc., belong in the same table that's meant to list operators by precedence?
msg176099 - (view) Author: Yongzhi Pan (fossilet) * Date: 2012-11-22 06:03
One possible solution:

We do not list priorities of the operations, instead link to the precedence table in the language reference.
msg176126 - (view) Author: Kiet Tran (ktt3ja) Date: 2012-11-22 21:33
Good idea.
msg176500 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-27 22:41
> I'm still unable to figure out how to do it

You could look at Doc/library/unittest.rst, there are some tables that span multiple lines.  If you want a newline in the output too I think you have to add a blank line in the cell.
msg176502 - (view) Author: Kiet Tran (ktt3ja) Date: 2012-11-28 01:05
That document actually doesn't have any table that spans multiple lines. Here's the html page: http://docs.python.org/dev/library/unittest.html

Actually, I already know how to make a table span multiple lines from this stackoverflow page: http://stackoverflow.com/questions/13504595/multi-line-table-cell-in-restructuredtext

However, the problem is having the items in different columns match, as it depends on the width of the table, which is not fixed. For example, notice how the table is formatted nicely here: http://imgur.com/y1hLg
But if I shrink the width, the formatting just goes wrong: http://imgur.com/Oct9m

This is particularly problematic because some elements in the table have long lines.
msg222408 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-07-06 15:43
I find the numeric operator predecence simply wrong, not confusing, so +1 from me for applying the attached patch from ktt3ja.  It's as simple as possible but no simpler :)
msg324561 - (view) Author: ron (ronron) Date: 2018-09-04 07:14
Any progress on this?
msg325900 - (view) Author: Elliot Edmunds (edmundselliot@gmail.com) Date: 2018-09-20 16:40
I agree that linking to the precedence table is probably the best solution.

A different option would be to add an extra column listing the "priority" and rank the priorities of the different operations.
msg329874 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2018-11-13 23:44
I'm actually thinking perhaps the "see :ref:`operator-summary`" clause should be separate and under Notes below the table, as opposed to current PR:

```
All numeric types (except complex) support the following operations (for priorities of
the operations, see :ref:`operator-summary`)
```

reads oddly to me.
msg351790 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2019-09-11 09:58
New changeset 4576b5431bd597df7581fe3c852b315e47e4b230 by Julien Palard (Anjali) in branch 'master':
bpo-16438: Doc: confusing text regarding numeric precedence corrected (GH-10521)
https://github.com/python/cpython/commit/4576b5431bd597df7581fe3c852b315e47e4b230
msg351804 - (view) Author: miss-islington (miss-islington) Date: 2019-09-11 10:39
New changeset 80db4b4be54ccdb5b67821506b6db2b27bd7c28a by Miss Islington (bot) in branch '3.8':
bpo-16438: Doc: confusing text regarding numeric precedence corrected (GH-10521)
https://github.com/python/cpython/commit/80db4b4be54ccdb5b67821506b6db2b27bd7c28a
msg351806 - (view) Author: miss-islington (miss-islington) Date: 2019-09-11 10:41
New changeset 9210b5826fab5248ac28a15c1b8b39ae949d0ef8 by Miss Islington (bot) in branch '3.7':
bpo-16438: Doc: confusing text regarding numeric precedence corrected (GH-10521)
https://github.com/python/cpython/commit/9210b5826fab5248ac28a15c1b8b39ae949d0ef8
History
Date User Action Args
2019-09-11 10:41:52mdksetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-09-11 10:41:30miss-islingtonsetmessages: + msg351806
2019-09-11 10:39:39miss-islingtonsetnosy: + miss-islington
messages: + msg351804
2019-09-11 09:58:46miss-islingtonsetpull_requests: + pull_request15546
2019-09-11 09:58:40miss-islingtonsetpull_requests: + pull_request15545
2019-09-11 09:58:30mdksetnosy: + mdk
messages: + msg351790
2018-11-13 23:44:33Mariattasetnosy: + Mariatta
messages: + msg329874
2018-11-13 19:40:10anjalimaliksetstage: needs patch -> patch review
pull_requests: + pull_request9781
2018-09-20 16:40:44edmundselliot@gmail.comsetnosy: + edmundselliot@gmail.com
messages: + msg325900
2018-09-04 11:00:46BreamoreBoysetnosy: - BreamoreBoy
2018-09-04 07:14:15ronronsetnosy: + ronron
messages: + msg324561
2014-07-06 15:43:41BreamoreBoysetnosy: + BreamoreBoy

messages: + msg222408
versions: + Python 3.5, - Python 3.2, Python 3.3
2012-11-28 01:05:43ktt3jasetmessages: + msg176502
2012-11-27 22:41:58ezio.melottisetmessages: + msg176500
2012-11-22 21:33:24ktt3jasetfiles: + 16438.patch
keywords: + patch
messages: + msg176126
2012-11-22 06:03:08fossiletsetmessages: + msg176099
2012-11-22 02:08:18ktt3jasetnosy: + ktt3ja
messages: + msg176088
2012-11-08 22:01:20ezio.melottisetkeywords: + easy
nosy: + ezio.melotti

type: enhancement
stage: needs patch
2012-11-08 20:42:47meador.ingesetnosy: + meador.inge
2012-11-08 15:29:14jceasetstatus: closed -> open
resolution: not a bug -> (no value)
messages: + msg175178
2012-11-08 15:18:05fossiletsetmessages: + msg175172
2012-11-08 14:30:58mark.dickinsonsetstatus: open -> closed
2012-11-08 14:27:06jceasetresolution: not a bug

messages: + msg175168
nosy: + jcea
2012-11-08 14:19:31fossiletcreate