[Python-checkins] bpo-26701: Add documentation for __trunc__ (GH-6049)

Nick Coghlan webhook-mailer at python.org
Sat Mar 10 10:10:40 EST 2018

commit: f34e0d60e27acff3f9604ec63e9de36878c3743a
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Nick Coghlan <ncoghlan at gmail.com>
date: 2018-03-11T01:10:32+10:00

bpo-26701: Add documentation for __trunc__ (GH-6049)

`int` fails back to `__trunc__` is `__int__` isn't defined, so cover
that in the docs.
(cherry picked from commit 308eab979d153f1ab934383dc08bc4546ced8b6c)

Co-authored-by: Eric Appelt <eric.appelt at gmail.com>

M Doc/library/functions.rst
M Doc/library/math.rst
M Doc/reference/datamodel.rst

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 3ddd280f77eb..c3b638572338 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -731,8 +731,11 @@ are always available.  They are listed here in alphabetical order.
    Return an integer object constructed from a number or string *x*, or return
    ``0`` if no arguments are given.  If *x* is a number, return
-   :meth:`x.__int__() <object.__int__>`.  For floating point numbers, this
-   truncates towards zero.
+   :meth:`x.__int__() <object.__int__>`. If *x* defines
+   :meth:`x.__trunc__() <object.__trunc__>` but not
+   :meth:`x.__int__() <object.__int__>`, then return
+   if :meth:`x.__trunc__() <object.__trunc__>`.  For floating point numbers,
+   this truncates towards zero.
    If *x* is not a number or if *base* is given, then *x* must be a string,
    :class:`bytes`, or :class:`bytearray` instance representing an :ref:`integer
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 55eb41b86f5d..33aec573a1f2 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -203,7 +203,7 @@ Number-theoretic and representation functions
    Return the :class:`~numbers.Real` value *x* truncated to an
    :class:`~numbers.Integral` (usually an integer). Delegates to
-   ``x.__trunc__()``.
+   :meth:`x.__trunc__() <object.__trunc__>`.
 Note that :func:`frexp` and :func:`modf` have a different call/return pattern
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 8b127a0b7e81..26ad7b8c050c 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -2377,6 +2377,15 @@ left undefined.
    of the appropriate type.
+.. method:: object.__trunc__(self)
+   Called to implement :meth:`math.trunc`.  Should return the value of the
+   object truncated to a :class:`numbers.Integral` (typically an
+   :class:`int`).  If a class defines :meth:`__trunc__` but not
+   :meth:`__int__`, then :meth:`__trunc__` is called to implement the
+   built-in function :func:`int`.
 .. method:: object.__index__(self)
    Called to implement :func:`operator.index`, and whenever Python needs to

More information about the Python-checkins mailing list