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.

Attached is the patch to update the documentation.

Please review. Thanks :)

Hmm, I did not mean to replace the documentation example like that.
Here's another update.

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.

Thanks for the feedback :) Makes sense, I'll work on another patch.

Here is an updated patch.
Please review :)
Thanks.

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.

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.

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

Mariatta, thank you for the patch.  And Chris, thanks for the observant bug report.

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

Thanks, Raymond and Martin :)

Not sure what the procedure is for fixing this. Do I upload another patch?

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.

Attaching an improved list example:
* Replaced abstract and hard to follow numerical example with fruits
* Demonstrate the non-mutating methods first

Thanks Raymond. The new set of examples is much better than the previous one.
+1

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

Okay, applied.

I backported these changes to 3.5 branch.
Please let me know if this is ok.

Thanks.