classification
Title: [doc] Range tutorial shorthand could be made clearer
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Chas Belov, cheryl.sabella, docs@python, iritkatriel, jack__d, miss-islington, rahul-kumi, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2020-05-14 06:12 by Chas Belov, last changed 2021-06-27 19:53 by iritkatriel. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 26919 merged jack__d, 2021-06-26 21:42
PR 26927 merged miss-islington, 2021-06-27 19:27
PR 26928 merged miss-islington, 2021-06-27 19:27
Messages (7)
msg368817 - (view) Author: Chas Belov (Chas Belov) * Date: 2020-05-14 06:12
I found https://docs.python.org/3.7/tutorial/controlflow.html#the-range-function section 4.3 confusing. The range() Function shows the following example:

>>> for i in range(5):
...     print(i)
...
0
1
2
3
4

[some instructional text]

range(5, 10)
   5, 6, 7, 8, 9

range(0, 10, 3)
   0, 3, 6, 9

range(-10, -100, -30)
  -10, -40, -70

This appears to be an instruction to type, for example:
range(5, 10)
at the prompt, and that the response will be:
   5, 6, 7, 8, 9

leading to a perceived bug when I type at the prompt:
>>> range(5, 10)
and receive the response
range(5, 10)

I ultimately figured out that the example is a shorthand to substitute
range(5, 10)
for the original 
range(5)

>>> for i in range(5, 10):
...     print(i)
...
5
6
7
8
9

It would be less confusing if the example instead read:

----------------------------

Substituting "range(5, 10)" for "range(5)" results in (one number per line)
5, 6, 7, 8, 9

Substituting "range(0, 10, 3)" results in
0, 3, 6, 9

and substituting "range(-10, -100, -30)" results in
-10, -40, -70

---------------------------

such that it is clear that the statements are not meant to be taken as literal stand-alone entries to be typed at the prompt but are instead substitutions.
msg368998 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-05-16 01:44
This block is the same in 3.9 and 3.8.

My first though is this block is a holdover from 2.7, where range returned list.  But looking at what is written previously, I think your interpretation is correct -- and agree that something other that code and corresponding output in a code block is confusing.  So this might better be a list than a code block.  Cheryl, do you have an idea of what might be better?
msg396557 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-06-26 21:01
Another alternative is to make the example *be* interactive.
This would also teach the easy, standard, and often better way to see the output of an iterable.

>>> list(range(5, 10))
[5, 6, 7, 8, 9]
>>> list(range(0, 10, 3))
[0, 3, 6, 9]
>>> list(range(-10, -100, -30))
[-10, -40, -70]
msg396596 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-27 19:27
New changeset 2f49c9debc2efe010c757be3bdbd6493f1ebc5f6 by jdevries3133 in branch 'main':
bpo-40620: Clarify tutorial controlflow.rst ``range`` examples (GH-26919)
https://github.com/python/cpython/commit/2f49c9debc2efe010c757be3bdbd6493f1ebc5f6
msg396597 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-27 19:51
New changeset aeb63392e74976b4289b38f32f1d6e7ff2e0a712 by Miss Islington (bot) in branch '3.10':
bpo-40620: Clarify tutorial controlflow.rst ``range`` examples (GH-26919) (GH-26927)
https://github.com/python/cpython/commit/aeb63392e74976b4289b38f32f1d6e7ff2e0a712
msg396598 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-27 19:52
New changeset 1acd1e63850d179383fcb638dcefee4c66b3ca4e by Miss Islington (bot) in branch '3.9':
bpo-40620: Clarify tutorial controlflow.rst ``range`` examples (GH-26919) (GH-26928)
https://github.com/python/cpython/commit/1acd1e63850d179383fcb638dcefee4c66b3ca4e
msg396599 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-27 19:53
Thank you Jack!
History
Date User Action Args
2021-06-27 19:53:33iritkatrielsetstatus: open -> closed
resolution: fixed
messages: + msg396599

stage: patch review -> resolved
2021-06-27 19:52:36iritkatrielsetmessages: + msg396598
2021-06-27 19:51:44iritkatrielsetmessages: + msg396597
2021-06-27 19:27:55iritkatrielsetnosy: + iritkatriel
messages: + msg396596
2021-06-27 19:27:38miss-islingtonsetpull_requests: + pull_request25498
2021-06-27 19:27:34miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request25497
2021-06-26 21:42:56jack__dsetkeywords: + patch
nosy: + jack__d

pull_requests: + pull_request25492
stage: needs patch -> patch review
2021-06-26 21:01:39terry.reedysetmessages: + msg396557
2021-06-23 16:59:29iritkatrielsetkeywords: + easy
title: Range tutorial shorthand could be made clearer -> [doc] Range tutorial shorthand could be made clearer
versions: + Python 3.10, Python 3.11, - Python 3.7, Python 3.8
2020-05-18 16:42:53rahul-kumisetnosy: + rahul-kumi
2020-05-16 01:44:10terry.reedysetassignee: docs@python
type: behavior
components: + Documentation
versions: + Python 3.8, Python 3.9
nosy: + docs@python, cheryl.sabella, terry.reedy

messages: + msg368998
stage: needs patch
2020-05-14 06:12:52Chas Belovcreate