[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.

--
resolution:  -> rejected
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Miki Tebeka]

Miki Tebeka  added the comment:

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.

--
nosy: +tebeka

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Anthony Flury]

Anthony Flury  added the comment:

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.

--
resolution: not a bug -> 
status: closed -> open

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.

--
resolution:  -> not a bug
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Anthony Flury]

Change by Anthony Flury :


--
assignee:  -> docs@python
components: +Documentation
nosy: +docs@python

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Anthony Flury]

Change by Anthony Flury :


--
type:  -> enhancement

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Anthony Flury]

Change by Anthony Flury :


--
pull_requests: +24015
pull_request: https://github.com/python/cpython/pull/25279

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Anthony Flury]

Change by Anthony Flury :


--
keywords: +patch
pull_requests: +23957
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/25220

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Anthony Flury]

Anthony Flury  added the comment:

I am working on a pull request for this.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Anthony Flury]

Anthony Flury  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Serhiy Storchaka]

Change by Serhiy Storchaka :


--
nosy: +lemburg, mark.dickinson, rhettinger, stutzbach

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Steven D'Aprano]

Steven D'Aprano  added the comment:

> 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

--
nosy: +steven.daprano

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43737] Documentation of modulo operator should document behaviour clearly when second operator is negative

[Anthony Flury]

New submission from Anthony Flury :

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 ?

--
messages: 390264
nosy: anthony-flury
priority: normal
severity: normal
status: open
title: Documentation of modulo operator should document behaviour clearly when 
second operator is negative

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com