[docs] [issue31042] Inconsistency in documentation of operator.index

[Raymond Hettinger]

Raymond Hettinger added the comment:

This seems like a generic issue for magic methods and is already covered by "for custom classes, implicit invocations of special methods are only guaranteed to work correctly if defined on an object’s type, not in the object’s instance dictionary."

While you're technically correct with suggesting "Equivalent to `type(a).__index__(a)`", I don't think this is an improvement.  It makes the docs safe against overly pedantic readings, but it also reduces the intelligibility for everyday users.

The usual approach in the docs is to say "a[b] <==> a.__getitem__(b)" rather than "a[b] <==> type(a).__getitem__(a, b)".  The latter is more correct but it is also less helpful.  For the most part, this style of presentation has worked well for a lot of people for a long time.

I recommend closing this or not doing any more than changing "Equivalent to:" to "Roughly equivalent to:".

----------
nosy: +rhettinger
priority: normal -> low

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue31042>
_______________________________________