[issue28197] range.index mismatch with documentation
New submission from Vedran Čačić:
Look at this:
>>> from collections.abc import Sequence
>>> help(Sequence.index)
index(self, value, start=0, stop=None)
S.index(value, [start, [stop]]) -> integer -- return first index of value.
Raises ValueError if the value is not present.
>>> issubclass(range, Sequence)
True
>>> help(range.index)
index(...)
rangeobject.index(value, [start, [stop]]) -> integer -- return index of value.
Raise ValueError if the value is not present.
So far, so good. But:
>>> range(9).index(2, 1, 5)
TypeError: index() takes exactly one argument (3 given)
Of course it's not essential, but the docs shouldn't lie. And if range _is_ a Sequence, then it should have the complete interface of a Sequence. Including start and end arguments for .index: they are optional from the point of call, not from the point of implementation. :-)
----------
assignee: docs@python
components: Documentation, Library (Lib)
messages: 276908
nosy: docs@python, veky
priority: normal
severity: normal
status: open
title: range.index mismatch with documentation
type: behavior
versions: Python 3.5, Python 3.6
_______________________________________
Python tracker
Changes by SilentGhost
Serhiy Storchaka added the comment:
Parameters start and stop were added to the Sequence.index() mixin method in issue23086. These broke some concrete Sequence implementations.
----------
nosy: +Devin Jeanpierre, rhettinger, serhiy.storchaka
_______________________________________
Python tracker
Vedran Čačić added the comment:
Yes, that's the precise reason I caught this. I was implementing some tools to do with Sequences (seqtools, like itertools but having non-ephemeral output given non-ephemeral input), and the Sequence that was easiest to test quickly was range. In `positions` (like .index but gives all the places a value appears), it raised TypeError.
----------
_______________________________________
Python tracker
Raymond Hettinger added the comment:
These broke some concrete Sequence implementations.
Poor choice of words. The concrete implementations didn't change at all.
Perhaps the concrete implementation need to be brought more in-sync with the ABC. That would be reasonable; afteralll the goal is substitutability -- that is the only reason that the old xrange morphed into something with nearly useless count() and index() methods in the first place.
----------
_______________________________________
Python tracker
Vedran Čačić added the comment:
Yes, I agree these are useless _if you know you're dealing with range_. However, if you have a Sequence, it would be very useful not to have range be a special case.
Of course, one solution is to have a default .index implementation in the Sequence ABC itself, but still I'd argue that range can implement the 3-arg .index much better than generic Sequence.
----------
_______________________________________
Python tracker
Raymond Hettinger added the comment:
I'd argue that range can implement the 3-arg .index much better than generic Sequence.
Yes, the range index() method should implement all three arguments. That shouldn't be difficult.
----------
assignee: docs@python ->
type: behavior -> enhancement
versions: -Python 3.5, Python 3.6
_______________________________________
Python tracker
Serhiy Storchaka added the comment:
Sorry for poor words. I was not going to blame anybody. But changing interface always is dangerous. It makes third-party classes that implemented the interface no longer valid substitutions.
I think two things are worth to be done:
1) Explicitly document (including the docstring) that the support of stop and start arguments is optional. Not all sequences implements it. 3.5+.
2) Add the support of stop and start arguments to range() in 3.7.
And would be nice to provide a way for testing if the sequence supports extended index(). If this is possible.
----------
_______________________________________
Python tracker
Raymond Hettinger added the comment:
2) Add the support of stop and start arguments to range() in 3.7.
Yes, the whole point of adding these bogus methods in the first place was to harmonize the range object with other sequence types.
----------
_______________________________________
Python tracker
Vedran Čačić added the comment:
Why can't this go into 3.6? To me this situation seems like a bug.
----------
_______________________________________
Python tracker
Raymond Hettinger added the comment:
Why can't this go into 3.6?
Because it is a new feature and we're already past beta 1; because nothing is actually broken; and because it is a very minor issue (x isn't 100% consistent with y); because this would depend on new code and tests that we haven't written yet; and because the use case for the optional arguments is to do repeated searches and that doesn't make much sense in the context of a range object. That said, I think it is harmless to add this to 3.7 even though it isn't very useful.
----------
assignee: -> rhettinger
_______________________________________
Python tracker
Change by Serhiy Storchaka
Change by Raymond Hettinger
Change by Serhiy Storchaka
Serhiy Storchaka
Change by Nitish
Nitish
Change by Shreyan Avigyan
participants (6)
-
Nitish -
Raymond Hettinger
-
Serhiy Storchaka
-
Shreyan Avigyan
-
SilentGhost
-
Vedran Čačić