classification
Title: Documentation of modulo operator should document behaviour clearly when second operator is negative
Type: enhancement Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: anthony-flury, docs@python, lemburg, mark.dickinson, rhettinger, steven.daprano, stutzbach, tebeka
Priority: normal Keywords: patch

Created on 2021-04-05 21:49 by anthony-flury, last changed 2021-04-10 15:36 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 25220 closed anthony-flury, 2021-04-06 14:25
PR 25279 closed anthony-flury, 2021-04-08 11:51
Messages (9)
msg390264 - (view) Author: Anthony Flury (anthony-flury) * Date: 2021-04-05 21:49
The behavior of a%b when a is positive and b is negative can be suprising. 

I understand that the behavior is so that the identity 

a = (a//b)*b + a%b 

can be preserved regardless of the signs of a or b.

but the result is different from other languages which is why it can be surprising.

I would be happy to do the grunt work to make the changes if some can suggest where.

Do we - add a warning to the https://docs.python.org/3/tutorial/introduction.html#numbers page, or should we link to a new page that details and explains the behavior. Which is more 'pythonic' in terms of documentation ?
msg390265 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2021-04-05 23:29
> the result is different from other languages which is why it can be surprising.

Maybe the other languages should be documenting their surprising result, which fails to preserve the identity?

> Do we - add a warning to the [tutorial] page, or should we link to a new page that details and explains the behavior.

Neither. Warnings are for *dangerous or risky behaviour*, this is neither. And we surely don't need an entire new page just to document a minor piece of arithmetic behaviour.

The behaviour (although not the rationale for it) is already documented here:

https://docs.python.org/3/reference/expressions.html#binary-arithmetic-operations

although not here:

https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex

You could add a note to the table at the second link, and a FAQ next to this:

https://docs.python.org/3/faq/programming.html#why-does-22-10-return-3
msg390302 - (view) Author: Anthony Flury (anthony-flury) * Date: 2021-04-06 10:14
I take your point about warnings etc - but when you come from other languages the Python behavior can initially be very surprising.

The reference section has always seemed to be a very technical document, certainly not targeted at the usual audience of people using Python.

Most Python users don't consider that int/float etc would be in the standard library either - for most users the built-ins are not the same.

Can I suggest:

1) The identity that is mentioned on https://docs.python.org/3/reference/expressions.html#binary-arithmetic-operations should be made more clear - at the moment it is buried in a paragraph and easily missed.

2) The document https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex should also mention the identity and the need to preserve it.

3) A link fromhttps://docs.python.org/3/tutorial/introduction.html#numbers to the document https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex - the introductory tutorial should link to further detail where neccessary.
msg390321 - (view) Author: Anthony Flury (anthony-flury) * Date: 2021-04-06 12:18
I am working on a pull request for this.
msg390545 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-04-08 19:41
I agree with Steven that minor fact should not be given more weight.  It has a specification in the Reference and it own FAQ entry.

IMO it doesn't belong in tutorial because having a negative modulus is rare and because burying the use in details makes the tutorial harder to read.  The intent of the tutorial is to have a structured, example driven, overview of the language.  It necessarily omits uncommon cases and detailed specifications.

Thanks for the suggestion, but I am going to close this one as Steven suggested.
msg390648 - (view) Author: Anthony Flury (anthony-flury) * Date: 2021-04-09 16:54
I fundamentally disagree with closing this - I know that this and many other 'quirks' catch beginners out, and the tutorial is what they use to learn.They don't look in the reference document - it is too dense in BNF definitions which turns a lot of people off from any other useful information - When I was researching this issue I didn't even think to look in the reference section.

Looking in the library section for information about the built-in types is also non-obvious to beginners. 

If the tutorial doesn't contain the detail, and doesn't link to the detail then beginners are left entirely puzzled by the behavior.

Given how difficult it is to search the documentation if you don't know exactly what you are looking for, then how beginners would know to look at the FAQ is beyond me. Having communicated with a number of beginners on a number of issues they had no idea that the FAQ even existed.

The change didn't 'bury the tutorial in detail' - it added once sentence which linked to the FAQ. In fact all the change did was expand the FAQ entry by a few lines and link to the FAQ from the three places that are relevant.

I think this is a small change and it should be the start of making the tutorial beginner friendly.
msg390691 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-04-10 04:50
Negative modulo divisors is not a "beginner friendly" topic or even remotely relevant to most users.  It is also trivially discoverable with a few seconds of experimentation at the interactive prompt.  FWIW, I've read dozens of Python tutorials and don't recall a single one covering this case.  We need a better reason to do this other than you insisting on it.
msg390694 - (view) Author: Miki Tebeka (tebeka) * Date: 2021-04-10 05:36
I agree with Raymond, this is not "beginner friendly".

I've been using Python for 25 year and teaching it for about 10 and this topic never came up.
msg390719 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-04-10 15:36
I just checked with another Python expert who reported:
"""
I have never once in my whole life seen or used a negative modulo. And that says a lot given that 6 years of it was spent studying math. Including a few years in a math PhD program.

Perhaps my only "surprise" on negative modulo is finding out that the classic gcd algorithm works fine if you give it negative integers.
"""

The reviewer inputs a unanimous.  Marking this as closed.  Please do not be rude and reopen again.
History
Date User Action Args
2021-04-10 15:36:55rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg390719
2021-04-10 05:36:41tebekasetnosy: + tebeka
messages: + msg390694
2021-04-10 04:50:40rhettingersetnosy: lemburg, rhettinger, mark.dickinson, stutzbach, steven.daprano, docs@python, anthony-flury
messages: + msg390691
2021-04-09 16:54:43anthony-flurysetstatus: closed -> open
resolution: not a bug -> (no value)
messages: + msg390648
2021-04-08 19:41:16rhettingersetstatus: open -> closed
resolution: not a bug
messages: + msg390545

stage: patch review -> resolved
2021-04-08 14:33:29anthony-flurysetassignee: docs@python

components: + Documentation
nosy: + docs@python
2021-04-08 14:33:12anthony-flurysettype: enhancement
2021-04-08 11:51:02anthony-flurysetpull_requests: + pull_request24015
2021-04-06 14:25:53anthony-flurysetkeywords: + patch
stage: patch review
pull_requests: + pull_request23957
2021-04-06 12:18:11anthony-flurysetmessages: + msg390321
2021-04-06 10:14:41anthony-flurysetmessages: + msg390302
2021-04-06 07:39:10serhiy.storchakasetnosy: + lemburg, rhettinger, mark.dickinson, stutzbach
2021-04-05 23:29:08steven.dapranosetnosy: + steven.daprano
messages: + msg390265
2021-04-05 21:49:56anthony-flurycreate