classification
Title: list.index documentation missing start and stop arguments
Type: Stage:
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: ChrisRands, Mariatta, akuchling, docs@python, martin.panter, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2016-11-02 09:32 by ChrisRands, last changed 2017-02-25 21:40 by Mariatta. This issue is now closed.

Files
File name Uploaded Description Edit
issue28587.patch Mariatta, 2016-11-02 13:05 review
issue28587.patch Mariatta, 2016-11-02 13:24 review
issue28587v3.patch Mariatta, 2016-11-06 21:26 add comment to list index example review
issue28587v4.patch Mariatta, 2016-11-12 15:57 review
new_list_example.diff rhettinger, 2016-11-22 00:05 Improved list example review
Pull Requests
URL Status Linked Edit
PR 299 merged Mariatta, 2017-02-25 21:38
Messages (18)
msg279913 - (view) Author: (ChrisRands) * Date: 2016-11-02 09:32
In Python 3 and 2 docs https://docs.python.org/3.5/tutorial/datastructures.html, list.index only mentions the first argument:


list.index(x)

    Return the index in the list of the first item whose value is x. It is an error if there is no such item.

However, in reality list.index can take further arguments:

index(...)
    L.index(value, [start, [stop]]) -> integer -- return first index of value.
    Raises ValueError if the value is not present.
msg279924 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-11-02 13:05
Attached is the patch to update the documentation.

Please review. Thanks :)
msg279925 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-11-02 13:24
Hmm, I did not mean to replace the documentation example like that.
Here's another update.
msg280164 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2016-11-06 18:57
The patch looks fine, though I suggest clarifying the example for a.index(333, 2)  by adding a comment such as '# begin searching at index 2' to explain what's going on.
msg280165 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-11-06 19:07
Thanks for the feedback :) Makes sense, I'll work on another patch.
msg280176 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-11-06 21:26
Here is an updated patch.
Please review :)
Thanks.
msg280634 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-11-12 06:00
This patch looks very good and I especially like the example.

One nit.  It may be insufficient to say that the start/end arguments are interpreted the same as the slice notation.  While that clear indicates the range being searched, it is silent on whether the index result is relative to index zero or relative to the start argument.
msg280662 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-11-12 15:57
Thanks for the feedback, Raymond :)

I rephrased the docs like the following, what do you think?

Return zero-based index in the list of the first item whose value is *x*.  It is an error if there is no such item.  Optional arguments ``start`` and ``end`` are interpreted as in slice notation.
msg281403 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-11-21 23:13
New changeset 62c16fafa7d4 by Raymond Hettinger in branch '3.6':
Issue 28587:  list.index documentation missing start and stop arguments. (Contributed by Mariatta Wijaya.)
https://hg.python.org/cpython/rev/62c16fafa7d4
msg281404 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-11-21 23:14
Mariatta, thank you for the patch.  And Chris, thanks for the observant bug report.
msg281408 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-11-21 23:41
The committed change looks wrong in the new example. I think Mariatta’s patch was right; it the index found is 3, not 2:

>>> a
[66.25, 333, -1, 333, 1, 1234.5, 333]
>>> a.index(333)
1
>>> a.index(333, 2)  # search for 333 starting at index 2
3
msg281409 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-11-21 23:52
Thanks, Raymond and Martin :)

Not sure what the procedure is for fixing this. Do I upload another patch?
msg281410 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-11-21 23:53
Thanks for noticing.   I tested against the original list rather than the subsequently modified version.  I'm starting to think that this whole example section is annoyingly hard to follow and uninformative.
msg281411 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-11-22 00:05
Attaching an improved list example:
* Replaced abstract and hard to follow numerical example with fruits
* Demonstrate the non-mutating methods first
msg281412 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-11-22 00:14
Thanks Raymond. The new set of examples is much better than the previous one.
+1
msg281415 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-11-22 00:32
New changeset efac7ac53933 by Raymond Hettinger in branch '3.6':
Issue #28587: Improve list examples in the tutorial
https://hg.python.org/cpython/rev/efac7ac53933
msg281417 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-11-22 00:33
Okay, applied.
msg288583 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-02-25 21:40
I backported these changes to 3.5 branch.
Please let me know if this is ok.

Thanks.
History
Date User Action Args
2017-02-25 21:40:23Mariattasetmessages: + msg288583
versions: + Python 3.5
2017-02-25 21:38:15Mariattasetpull_requests: + pull_request266
2016-11-22 00:33:28rhettingersetstatus: open -> closed

messages: + msg281417
2016-11-22 00:32:06python-devsetmessages: + msg281415
2016-11-22 00:14:42Mariattasetmessages: + msg281412
2016-11-22 00:05:47rhettingersetfiles: + new_list_example.diff

messages: + msg281411
2016-11-21 23:53:26rhettingersetmessages: + msg281410
2016-11-21 23:52:01Mariattasetmessages: + msg281409
2016-11-21 23:41:24martin.pantersetstatus: closed -> open
versions: + Python 3.6, Python 3.7
nosy: + martin.panter

messages: + msg281408
2016-11-21 23:14:45rhettingersetstatus: open -> closed
resolution: fixed
messages: + msg281404
2016-11-21 23:13:47python-devsetnosy: + python-dev
messages: + msg281403
2016-11-12 15:57:04Mariattasetfiles: + issue28587v4.patch

messages: + msg280662
2016-11-12 06:00:57rhettingersetmessages: + msg280634
2016-11-06 21:26:56Mariattasetfiles: + issue28587v3.patch

messages: + msg280176
2016-11-06 19:07:18Mariattasetmessages: + msg280165
2016-11-06 18:57:44akuchlingsetnosy: + akuchling
messages: + msg280164
2016-11-02 13:24:18Mariattasetfiles: + issue28587.patch

messages: + msg279925
2016-11-02 13:18:16serhiy.storchakasetassignee: docs@python -> rhettinger

nosy: + rhettinger
2016-11-02 13:05:58Mariattasetfiles: + issue28587.patch

nosy: + Mariatta
messages: + msg279924

keywords: + patch
2016-11-02 09:32:23ChrisRandscreate