Specify that dunder get/set item accepts SupportsIndex

[honno]

Currently __getitem__()/__setitem__() accept array as keys, which implicitly has to be boolean arrays, or 0d integer arrays i.e. has a working __index__(). The latter is not an obvious concept to grasp, and maybe not even quite specified anyway.

I propose we add the stdlib typing.SupportsIndex to the get/set item signatures, specifically before array. This does add support for any indexable type, but that seems okay, and was the intention anyway when __index__() was proposed in #231. I also think a note would be helpful in regards to what arrays are accepted, e.g.:

key can only be an array if it is valid for boolean array indexing, or supports __index__() i.e. is a 0-dimensional integer array.

cc @kgryte @asmeurer

[asmeurer]

Just to be clear, the point of __index__ isn't just to support 0d integer arrays as indices on arrays, but to let them be indices on any type that supports integer indexing like str and list. And conversely, for arrays to accept as integer indices any type that implements __index__ (with the exception of bool, which unfortunately inherits it from int but usually has a different indexing meaning for arrays).

i.e. is a 0-dimensional integer array.

I would omit this part. Any type can implement __index__. That's the whole point. In fact, we might link to PEP 357 instead of the spec __index__ definition.

[kgryte]

@honno Would you be willing to open a PR addressing this issue for the v2024 revision?