Documentation about comparisons between numeric types is misleading

[mdickinson]

BPO	39530
Nosy	@terryjreedy, @mdickinson, @KatherineMichel, @miss-islington
PRs	bpo-39530: Fix misleading statement about mixed-type numeric comparisons #18615 [3.7] bpo-39530 Fix misleading statement about mixed-type numeric comparisons (GH-18615) #18737 [3.8] bpo-39530 Fix misleading statement about mixed-type numeric comparisons (GH-18615) #18736 [3.8] (bpo-39530) Fix misleading statement about mixed-type numeric comparisons (GH-18615) #18773

^{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-03-04.17:45:59.511>
created_at = <Date 2020-02-02.14:17:34.755>
labels = ['3.7', '3.8', '3.9', 'docs']
title = 'Documentation about comparisons between numeric types is misleading'
updated_at = <Date 2020-03-04.17:46:22.998>
user = 'https://github.com/mdickinson'

bugs.python.org fields:

activity = <Date 2020-03-04.17:46:22.998>
actor = 'mark.dickinson'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-03-04.17:45:59.511>
closer = 'mark.dickinson'
components = ['Documentation']
creation = <Date 2020-02-02.14:17:34.755>
creator = 'mark.dickinson'
dependencies = []
files = []
hgrepos = []
issue_num = 39530
keywords = ['patch']
message_count = 6.0
messages = ['361234', '361235', '361752', '361788', '362702', '363364']
nosy_count = 5.0
nosy_names = ['terry.reedy', 'mark.dickinson', 'docs@python', 'Katherine Michel', 'miss-islington']
pr_nums = ['18615', '18737', '18736', '18773']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue39530'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

[mdickinson]

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

[mdickinson]

Related SO question: https://stackoverflow.com/questions/60005876/how-does-python-compare-int-to-float-objects

[KatherineMichel]

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.

[mdickinson]

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.

[mdickinson]

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?

[mdickinson]

Thank you for reviewing!