[New-bugs-announce] [issue31042] Inconsistency in documentation of operator.index

[Joseph Fox-Rabinovitz]

New submission from Joseph Fox-Rabinovitz:

The docs for [`operator.index`][1] and `operator.__index__` state that

> Return *a* converted to an integer. Equivalent to `a.__index__()`.

The first sentence is correct, but the second is not. First of all, we have the data model [docs][2]:

> 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.

Secondly, we can make a simple counter-example in code:

```
import operator

class A:
    def __index__(self): return 0

a = A()
a.__index__ = (lambda self: 1).__get__(a, type(a))
operator.index(a)
```

The result is of course zero and not one.

I believe that the docs should read something more like one of the following to avoid being misleading:

> Return *a* converted to an integer, if it is already an integral type.

> Return *a* converted to an integer. Equivalent to `type(a).__index__(a)`.

Or a combination of both:

> Return *a* converted to an integer, if it is already an integral type. Equivalent to `type(a).__index__(a)`.

  [1]: https://docs.python.org/3/library/operator.html#operator.index
  [2]: https://docs.python.org/3/reference/datamodel.html#special-method-lookup

----------
assignee: docs at python
components: Documentation
messages: 299195
nosy: docs at python, madphysicist
priority: normal
severity: normal
status: open
title: Inconsistency in documentation of operator.index
type: behavior
versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7

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