classification
Title: documentation: alternate version of xrange seems to fail.
Type: Stage:
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eli.bendersky, eric.araujo, ezio.melotti, python-dev, rhettinger, tenuki, terry.reedy
Priority: normal Keywords:

Created on 2011-05-04 22:08 by tenuki, last changed 2011-05-23 03:11 by eli.bendersky. This issue is now closed.

Files
File name Uploaded Description Edit
test_xrange.py tenuki, 2011-05-04 22:08 test xrange alternate versions
Messages (10)
msg135159 - (view) Author: alejandro david weil (tenuki) Date: 2011-05-04 22:08
Python's documentation includes 2 source codes for alternate xrange implementations, which, at least in my tests, give unexpected results.

# from file:///usr/share/doc/python2.6-doc/html/library/functions.html#xrange
takewhile(lambda x:x<stop, (start+i*step for i in count()))

and:


# from: http://docs.python.org/library/functions.html?highlight=xrange#xrange
islice(count(start, step), (stop-start+step-1)//step)


I'll attach a file with source code showing that, and propose 3 different versions which seems to work fine. (I've prefer the first one, but python lacks of sign() function).
msg135337 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-06 17:18
Hi.  Python 2.6 is in security mode, its documentation is not updated nor released anymore.  Is this bug present in the documentation of 2.7 or 3.x versions?
msg135340 - (view) Author: alejandro david weil (tenuki) Date: 2011-05-06 17:23
Yes it is. I copied both versions but forgot to specify the second is in 2.7.

This is read in the current (2.7) documentation:
# from: http://docs.python.org/library/functions.html?highlight=xrange#xrange
islice(count(start, step), (stop-start+step-1)//step)

and test_xrange.py shows the output of this code against range(). The code includes 2 samples of parameters which gives the unexpected results.
msg135407 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-05-07 07:23
I verified bug on winxp with 2.7
xrangef [5, 4, 3, 2, 1, 0]
py26 []
py27 [5, 4, 3, 2, 1, 0, -1, -2]
v1 [5, 4, 3, 2, 1, 0]
v2 [5, 4, 3, 2, 1, 0]
v3 [5, 4, 3, 2, 1, 0]
-----------------------
xrangef [5, 3, 1, -1, -3]
py26 []
py27 [5, 3, 1, -1, -3, -5]
v1 [5, 3, 1, -1, -3]
v2 [5, 3, 1, -1, -3]
v3 [5, 3, 1, -1, -3]

The problem is that -1 should instead be +1 for negative steps. The 2.6 version completely failed for negative steps because the comparison needs to be reversed. The doc example could add "for positive steps. For negative steps, use '+1' instead of '-1'". Or change expression to
islice(count(start, step), (stop-start+step-1+2*(step<0))//step)
(the addition is  +2*(step<0)).
Or change -1 to +(-1 if step>0 else 1). I tested both.
msg136426 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-05-21 10:12
I think that if this note should stay in the docs at all, it should be as concise as possible, so I like Terry's -1+2*(step<0) option. I also tested it on a few more inputs and it works fine.

If there are no objections, I can commit it to python 2.7 docs in a couple of days.
msg136544 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-22 17:23
The docs should value readability over conciseness IMHO; the examples here with seven operations in a row are a bit scary.
msg136546 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-05-22 17:35
Éric, I'm not sure that the note is necessary at all, but once it's there, it should value *correctness* over conciseness and readability.
msg136574 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-05-22 20:59
Given that the note is already gone* as obsolete in 3.x, I think a minimal maintenance fix for correctness should be fine for 2.7.

* It is replaced, in essence, by "Ranges containing absolute values larger than sys.maxsize are permitted but some features (such as len()) will raise OverflowError."
msg136584 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-05-23 03:10
New changeset 76e5fe8e21fd by Eli Bendersky in branch '2.7':
Issue 12003: fixing error in xrange alternative sample
http://hg.python.org/cpython/rev/76e5fe8e21fd
msg136585 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-05-23 03:11
Agreed. 
Fix committed & issue closed.
History
Date User Action Args
2011-05-23 03:11:30eli.benderskysetstatus: open -> closed

messages: + msg136585
2011-05-23 03:10:52python-devsetnosy: + python-dev
messages: + msg136584
2011-05-22 20:59:10terry.reedysetmessages: + msg136574
2011-05-22 17:35:35eli.benderskysetmessages: + msg136546
2011-05-22 17:23:31eric.araujosetmessages: + msg136544
2011-05-21 10:12:39eli.benderskysetnosy: + eli.bendersky
messages: + msg136426
2011-05-07 07:23:49terry.reedysetnosy: + terry.reedy
messages: + msg135407
2011-05-06 17:23:46tenukisetmessages: + msg135340
2011-05-06 17:18:45eric.araujosetnosy: + eric.araujo

messages: + msg135337
versions: - Python 2.6
2011-05-05 10:25:28ezio.melottisetnosy: + rhettinger, ezio.melotti
2011-05-04 22:08:44tenukicreate