The documentation for the int(x) constructor explains that if possible, it delegates to x.__int__().   The documentation does not explain that there is a fallback to x.__trunc__() if x.__int__() is not available.

The only mention of __trunc__ in the Python documentation is in the entry for math.trunc; the documentation for the numbers module does not describe the underlying special methods.

Given that all Real numbers are required to implement __trunc__ but only Integral subclasses are required to implement __int__ this could be important to implementers of other Real types, although in practice I imagine that most Real types will implement __int__ as float does.

It is documented in the relevant PEP (pep 3141), but should indeed be added to the appropriate places in the regular documentation.

What about __floor__ and __ceil__?

I think all these three method do not deserve separate paragraphs in Doc/reference/datamodel.rst, but they should be grouped together with __round__.

New changeset 308eab979d153f1ab934383dc08bc4546ced8b6c by Nick Coghlan (Eric Appelt) in branch 'master':
bpo-26701: Add documentation for __trunc__ (GH-6022)
https://github.com/python/cpython/commit/308eab979d153f1ab934383dc08bc4546ced8b6c

I think __trunc__ is special here, as it's called by a built-in type constructor, whereas __floor__ and __ceil__ really are specific to their respective math module functions. That said, I also wouldn't be opposed to listing all 4 methods together (or else listing __floor__ and __ceil__ with the just added entry for __trunc__).

I also filed https://bugs.python.org/issue33039 to cover an anomaly Eric found after I suggested adding __index__ to the list of methods tried, which is that int() and math.trunc() *don't* call __index__ implicitly: the type has to set "__int__ = __index__" and "__trunc__ = __index__" to get them to work.

I suspect we just didn't notice when PEP 357 was implemented because the developers that wanted __index__ were adding it to types that *already* defined __int__ and __trunc__.

New changeset f34e0d60e27acff3f9604ec63e9de36878c3743a by Nick Coghlan (Miss Islington (bot)) in branch '3.7':
bpo-26701: Add documentation for __trunc__ (GH-6049)
https://github.com/python/cpython/commit/f34e0d60e27acff3f9604ec63e9de36878c3743a

New changeset 1028ca4f04c14cf40a8f3e7951623a96ec0143c2 by Nick Coghlan (Miss Islington (bot)) in branch '3.6':
bpo-26701: Add documentation for __trunc__ (GH-6050)
https://github.com/python/cpython/commit/1028ca4f04c14cf40a8f3e7951623a96ec0143c2

New changeset 496431ffb6c29719332bf2af773349e8dd85e45a by Serhiy Storchaka in branch 'master':
bpo-26701: Improve documentation for the rounding special methods. (#6054)
https://github.com/python/cpython/commit/496431ffb6c29719332bf2af773349e8dd85e45a

New changeset 89090789debb9d76892af566277cb71740808945 by Miss Islington (bot) in branch '3.7':
bpo-26701: Improve documentation for the rounding special methods. (GH-6054)
https://github.com/python/cpython/commit/89090789debb9d76892af566277cb71740808945

New changeset de8567e38c44b1509f0b906aec54437256848f14 by Miss Islington (bot) in branch '3.6':
bpo-26701: Improve documentation for the rounding special methods. (GH-6054)
https://github.com/python/cpython/commit/de8567e38c44b1509f0b906aec54437256848f14

With both Eric's and Serhiy's updates merged, and issue 33039 broken out for the __index__ oddities, this is resolved now.

New changeset df00f048250b9a07195b0e3b1c5c0161fdcc9db8 by Nick Coghlan (Serhiy Storchaka) in branch 'master':
bpo-26701: Tweak the documentation for special methods in int(). (GH-6741)
https://github.com/python/cpython/commit/df00f048250b9a07195b0e3b1c5c0161fdcc9db8

New changeset 22df4187c3882c6ec67180902e1151e65b03aee0 by Miss Islington (bot) in branch '3.7':
bpo-26701: Tweak the documentation for special methods in int(). (GH-6741)
https://github.com/python/cpython/commit/22df4187c3882c6ec67180902e1151e65b03aee0

New changeset 7488c79b600cd173b0ccea13adb567d078e7b835 by Miss Islington (bot) in branch '3.6':
bpo-26701: Tweak the documentation for special methods in int(). (GH-6741)
https://github.com/python/cpython/commit/7488c79b600cd173b0ccea13adb567d078e7b835