This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Python tutorial misleads users about floor division behavior
Type: Stage:
Components: Documentation Versions: Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: andrei.avk, docs@python, jessevsilverman, rhettinger, terry.reedy
Priority: normal Keywords:

Created on 2021-01-27 01:15 by jessevsilverman, last changed 2022-04-11 14:59 by admin.

Messages (5)
msg385746 - (view) Author: Jesse Silverman (jessevsilverman) Date: 2021-01-27 01:15
I had never worked thru the Python tutorial, it's kind of awesome.

I noticed multiple independent presenters incorrectly describe the behavior of floor division when the signs of the operands don't match.  Not just sloppy ones, some who are usually pretty careful -- people forget.  I found it odd.

Today I read:
https://docs.python.org/3.9/tutorial/introduction.html#using-python-as-a-calculator
'Division (/) always returns a float. To do floor division and get an integer result (discarding any fractional result) you can use the // operator; to calculate the remainder you can use %:'

I know what they mean (there will never be a non-zero fractional component in the result) however, stating that it "discards any fraction result" explicitly suggests that it will round towards zero for all results.  The name of the operator tells us the true story, as does a test, it rounds towards negative infinity for all results.

Hopefully all the people using Python to treat cancer, fly to Mars and run power plants know what the behavior is.  However, anecdotally, I have seen evidence that generally cautious, fairly-detail oriented programmers seem to forget the details of the behavior, this is one place in the docs from which many people first learn about the floor division operator and this page would lead me to believe it operates differently than it does in reality.

If the words right there don't get changed, or the example of -10/3 doesn't get added, would this be a good excuse for a third footnote?  I would actually wish for both the wording to be changed and to show an example like -10 / 3, tho admittedly I came from an Engineering background so I am always worried someone's going to blow up somewhere...

Deepest regards for everyone who gets to regularly close the complaints about floor division working as designed and documented -- but not quite documented on this page which more people may read than others covering the operator.
msg385840 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-01-28 06:16
The first section of the tutorial isn't the right place to go into these details.  The point of the section is to have a basic introduction to the interactive prompt.  It is intensionally gentle and lightweight.

It isn't the purpose of the tutorial to document complete semantics and corner cases.  We leave that for the language reference or for coverage of specific types in the library reference.  See footnote (1) in the operator table at https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex .
msg385932 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-01-29 20:12
-17/3 = -5.666666666666667 = -6.0 + .333333333333333.  It is the latter fraction that gets discarded.

However, this is a frequent source of confusion.  How about adding 

>>> -17 // 3
-6
>>> -17 % 3
1
>>> -6 * 3 + 1
-17

to illustrate what we mean, without footnote or additional text.
msg385952 - (view) Author: Jesse Silverman (jessevsilverman) Date: 2021-01-29 22:02
I understand and agree with both comments.
I will confirm that a substantial number of people think -17 // 3 yields -5.0, so when I saw this I wondered if it reinforced that common misconception.

I was curious enough to not just confirm in the actual docs not only that -17 // 3 == -6.0 but learned why it does so.

I would be happy to see any of Terry's three suggestions added, with the first one adding the most bang for the buck (if someone is surprised to see -6.0 there, they can go look up why).
msg397168 - (view) Author: Andrei Kulakov (andrei.avk) * (Python triager) Date: 2021-07-08 19:50
Possibly:

5//2  # 2
-5//2 # -3

Would be easier to understand.
History
Date User Action Args
2022-04-11 14:59:40adminsetgithub: 87200
2021-07-08 19:50:49andrei.avksetnosy: + andrei.avk
messages: + msg397168
2021-01-29 22:02:41jessevsilvermansetmessages: + msg385952
2021-01-29 20:12:45terry.reedysetnosy: + terry.reedy
messages: + msg385932
2021-01-28 06:16:05rhettingersetnosy: + rhettinger
messages: + msg385840
2021-01-27 01:15:02jessevsilvermancreate