Clarification on signature for `index`

[lgalfaso]

Documentation

The documentation reads that the signature for index (sequences, str, bytes) is .index(value[, start[, end]]), (the name of the first parameter changes depending on the underlying type). This leaves it open to interpretation whether any/all the parameters can be named parameters (that they cannot). Should the signature of these methods be .index(sub[, start[, end]], /)?

Ref: https://docs.python.org/3/library/stdtypes.html#sequence.index

Note: Tried looking whether there is some convention that specifies that if there are optional parameters in brackets, this means that the parameters are positional only, but was unable to find anything.

Linked PRs

• gh-152030: Clarify sequence.index() signature #152092

[skirpichev]

Should the signature of these methods be .index(sub[, start[, end]], /)

In all cases signatures could be represented in a valid Python syntax:

>>> import inspect
>>> inspect.signature(range.index)
<Signature (self, object, /)>
>>> inspect.signature(tuple.index)
<Signature (self, value, start=0, stop=9223372036854775807, /)>
>>> inspect.signature(list.index)
<Signature (self, value, start=0, stop=9223372036854775807, /)>

This is valid also for str/bytes. For some reasons (perhaps, leaking of the sys.maxsize value as a default for stop parameter) signatures were overriden here:

>>> inspect.signature(str.index)
Traceback (most recent call last):
[...]
ValueError: <method 'index' of 'str' objects> builtin has invalid signature

I think this should be fixed.

The documentation, probably, could be fixed by using multiple signatures:

sequence.index(value, /)
sequence.index(value, start=0, stop=sys.maxsize, /)

Tried looking whether there is some convention that specifies that if there are optional parameters in brackets

It's undocumented syntax, unfortunately. See e.g. https://discuss.python.org/t/95015/

[subscapularis]

Hi @skirpichev, I'd like to take this on as my first contribution to CPython. I will draft a PR to replace the old bracket syntax with the two explicit signatures using the positional-only / marker exactly as you suggested.