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: range docstring is less useful than in python 2
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Devin Jeanpierre, benjamin.peterson, docs@python, nedbat, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2014-11-02 21:07 by nedbat, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
22785.patch nedbat, 2015-04-22 00:00 review
Messages (4)
msg230525 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2014-11-02 21:07
The Python 3.4 docstring for range is:
{{{
 |  range(stop) -> range object
 |  range(start, stop[, step]) -> range object
 |
 |  Return a virtual sequence of numbers from start to stop by step.
}}}

In Python 2.7, it said:
{{{
    range(stop) -> list of integers
    range(start, stop[, step]) -> list of integers

    Return a list containing an arithmetic progression of integers.
    range(i, j) returns [i, i+1, i+2, ..., j-1]; start (!) defaults to 0.
    When step is given, it specifies the increment (or decrement).
    For example, range(4) returns [0, 1, 2, 3].  The end point is omitted!
    These are exactly the valid indices for a list of 4 elements.
}}}

Note that Python 3 seems to imply that the end-point is included, while Python 2 made clear that it was not.  "Arithmetic progression" is a bit involved, but it would be good to mention that the end-point is omitted in the Python 3 docstring.
msg230667 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-11-05 08:33
> Note that Python 3 seems to imply that the end-point is included

The Python 2 wording is better in this regard.

Also, it would be nice clarify what is meant by "virtual sequence".  I know what that means only because I already know what range() does.  For someone who doesn't already know what it means, that phrase probably doesn't add any value.
msg241758 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2015-04-22 00:00
(By the time I got to the source, the word "virtual" had been removed...)

Attached is a patch to make the help read:

 |  range(stop) -> range object
 |  range(start, stop[, step]) -> range object
 |
 |  Return an object that produces a sequence of integers from start (inclusive)
 |  to stop (exclusive) by step.  range(i, j) produces i, i+1, i+2, ..., j-1.
 |  start defaults to 0, and stop is omitted!  range(4) produces 0, 1, 2, 3.
 |  These are exactly the valid indices for a list of 4 elements.
 |  When step is given, it specifies the increment (or decrement).
msg241799 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-04-22 13:16
New changeset aa6b73823685 by Benjamin Peterson in branch '3.4':
improved range docstring (closes #22785)
https://hg.python.org/cpython/rev/aa6b73823685

New changeset c031fa8e6884 by Benjamin Peterson in branch 'default':
merge 3.4 (#22785)
https://hg.python.org/cpython/rev/c031fa8e6884
History
Date User Action Args
2022-04-11 14:58:09adminsetgithub: 66974
2015-04-22 13:16:38python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg241799

resolution: fixed
stage: needs patch -> resolved
2015-04-22 00:00:28nedbatsetfiles: + 22785.patch
keywords: + patch
messages: + msg241758
2015-03-02 08:36:57ezio.melottisetnosy: + benjamin.peterson
type: enhancement
2014-11-05 08:33:11rhettingersetnosy: + rhettinger
messages: + msg230667
2014-11-05 00:15:11pitrousetstage: needs patch
versions: + Python 3.5
2014-11-04 21:10:08Devin Jeanpierresetnosy: + Devin Jeanpierre
2014-11-02 21:07:03nedbatcreate