classification
Title: Documentation about comparisons between numeric types is misleading
Type: Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Katherine Michel, docs@python, mark.dickinson, miss-islington, terry.reedy
Priority: normal Keywords: patch

Created on 2020-02-02 14:17 by mark.dickinson, last changed 2020-03-04 17:46 by mark.dickinson. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 18615 merged mark.dickinson, 2020-02-23 13:30
PR 18737 merged miss-islington, 2020-03-03 16:18
PR 18736 closed miss-islington, 2020-03-04 10:08
PR 18773 merged miss-islington, 2020-03-04 10:30
Messages (6)
msg361234 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2020-02-02 14:17
The documentation[1] for comparisons between mixed types says:

> [...] when a binary arithmetic operator has operands of different
> numeric types, the operand with the "narrower" type is widened to
> that of the other, where integer is narrower than floating point,
> which is narrower than complex. Comparisons between numbers of
> mixed type use the same rule.

That "use the same rule" part of the last sentence is misleading: it suggests that (for example) when an int is compared with a float, the int is first converted to a float, and then the two floats are compared. But that's not what actually happens: instead, the exact values of the int and float are compared. (And it's essential that equality comparisons happen that way, else equality becomes intransitive and dictionaries with numeric keys get very confused as a result.)

I suggest dropping the last sentence and adding a new paragraph about comparisons between numbers of mixed type.




[1] https://github.com/python/cpython/blob/master/Doc/library/stdtypes.rst#numeric-types-----classint-classfloat-classcomplex
msg361235 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2020-02-02 14:21
Related SO question: https://stackoverflow.com/questions/60005876/how-does-python-compare-int-to-float-objects
msg361752 - (view) Author: Katherine Michel (Katherine Michel) * Date: 2020-02-10 23:48
I'm at the sprints at PyCascades and was looking for an issue to work on and came across this and wanted to know more about it. As I was doing some research, I found the terms "narrower" and "wider" to seem ambiguous. I'm assuming "narrower" to mean that an integer has a more precise value and "wider" to mean that a float has a less precise/wider range of possible values, but unless I'm missing something, it isn't clear. I think the first paragraph should be revised to make the meaning more explicit. Happy to assist (with some input), if applicable.
msg361788 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2020-02-11 07:20
Hi Katherine,

My report was really just about the last sentence, but I agree that the "narrower" language is confusing here. If someone says that a type "A" is narrower than type "B", that suggests to my ears that "A" represents a subset of the values of "B" (but conversely, that "B" can represent everything "A" can). That applies to the float/complex pair, or to Python 2's int/long, or to NumPy's float32/float64 or int32/int64, but not really to int/float, since int has many values that can't be represented as a float (and even has larger range than float).

I suspect that the wording may have made a bit (but only a bit) more sense in Python 2, where `long` was still in the mix, and `int` was the fixed-width type, which really would have been a subset of `float` on a typical 32-bit machine.

So yes, if we can find a way to ditch the "narrower" language altogether but still convey that idea of implicit conversions from int to float, and from float to complex, that would be good.

And then the last sentence still needs fixing somehow.
msg362702 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2020-02-26 17:08
There's a PR on GitHub. (GH-18615)

Terry: I think you've looked at similar sorts of documentation clarifications in the past. Would you have any interest in reviewing this one?
msg363364 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2020-03-04 17:46
Thank you for reviewing!
History
Date User Action Args
2020-03-04 17:46:22mark.dickinsonsetmessages: + msg363364
2020-03-04 17:45:59mark.dickinsonsetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2020-03-04 10:30:52miss-islingtonsetpull_requests: + pull_request18132
2020-03-04 10:08:07miss-islingtonsetpull_requests: + pull_request18131
2020-03-03 16:18:44miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request18127
2020-02-26 17:08:07mark.dickinsonsetnosy: + terry.reedy
messages: + msg362702
2020-02-23 13:30:39mark.dickinsonsetkeywords: + patch
stage: patch review
pull_requests: + pull_request17980
2020-02-11 07:20:20mark.dickinsonsetmessages: + msg361788
2020-02-10 23:48:53Katherine Michelsetnosy: + Katherine Michel
messages: + msg361752
2020-02-02 14:21:06mark.dickinsonsetmessages: + msg361235
2020-02-02 14:17:34mark.dickinsoncreate