bpo-26701: Add documentation for __trunc__

[appeltel]

Add explicit documentation of the __trunc__ method beyond the single mention in the math module.

Place the documentation for this method near to __int__, and explain that there is a fallback to x.__trunc__() if x.__int__() is not available.

https://bugs.python.org/issue26701

[ncoghlan]

Thanks for this! Your changes look good as far as __trunc__ goes, but they also make it clear that it's not only the __trunc__ path that isn't currently documented properly, but also the __index__ path.

Would you be amenable to adjusting the PR to cover __index__ as well?

[ncoghlan]

Since you're updating this paragraph anyway, it makes sense to mention __index__ as well, perhaps by converting to a bulleted list of conversion methods in order of priority: x.__index__(), x.__int__(), x.__trunc__().

[ncoghlan]

Mention __index__ here as well.

[appeltel]

@ncoghlan - yes, I'll update this tonight and incorporate your suggestions.

[appeltel]

@ncoghlan So I did some experimentation to try to ensure that I had the order of fallbacks correct, and after further investigation it seems that you can't call int() on an object that has only defined __index__. I can use it as an index, even call hex() on it, but not int():

>>> class Foo:
...     def __index__(self): return 4
... 
>>> f = Foo()
>>> [x for x in range(7)][f]
4
>>> int(f)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: int() argument must be a string, a bytes-like object or a number, not 'Foo'
>>> int(hex(f), 16)
4

This appears to be odd behavior in that something that is obviously designed to be interpreted as an int for the purposes of indexing and slicing can't be coerced into an int, and it seems backwards relative to the aim of PEP-357.

The source code for PyObject * PyNumber_Long(PyObject *o) also clearly does not check the nb_index slot, only nb_int. I found that I can clumsily add this capability by making an (PyLongObject *)_PyLong_FromNbIndex(PyObject *) function largely copied from (PyLongObject *)_PyLong_FromNbInt(PyObject *) but changing the slot, so I guess it was never there.

Maybe I am misreading the code, could you verify?

[ncoghlan]

@appeltel Huh, very strange. I guess the history there is that all of the objects that __index__ was added to help with already defined __int__, so all they needed was a protocol that allowed them to be used in the places that deliberately don't call the potentially lossy conversion methods.

[ncoghlan]

Since the handling of __index__ clearly isn't as straightforward as I thought, I'm going to go ahead and merge this based on the original scope - thanks!

[miss-islington]

Thanks @ncoghlan for merging it 🌮🎉.. I'm working now to backport this PR to: 3.6, 3.7.
🐍🍒⛏🤖

[bedevere-bot]

3.7 branch.

[bedevere-bot]

3.6 branch.