[issue26701] Documentation for int constructor mentions __int__ but not __trunc__
New submission from Robert Smallshire: 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. ---------- assignee: docs@python components: Documentation messages: 262941 nosy: Robert Smallshire2, docs@python priority: normal severity: normal status: open title: Documentation for int constructor mentions __int__ but not __trunc__ type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26701> _______________________________________
R. David Murray added the comment: It is documented in the relevant PEP (pep 3141), but should indeed be added to the appropriate places in the regular documentation. ---------- nosy: +r.david.murray versions: +Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26701> _______________________________________
Change by Eric Appelt <eric.appelt@gmail.com>: ---------- keywords: +patch pull_requests: +5788 stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment: 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__. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: 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/308eab979d153f1ab934383dc08bc4546ce... ---------- nosy: +ncoghlan _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +5810 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +5811 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: 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__. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- pull_requests: +5815 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: 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/f34e0d60e27acff3f9604ec63e9de36878c... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: 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/1028ca4f04c14cf40a8f3e7951623a96ec0... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment: 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/496431ffb6c29719332bf2af773349e8dd8... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +5817 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +5818 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: 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/89090789debb9d76892af566277cb717408... ---------- nosy: +miss-islington _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: 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/de8567e38c44b1509f0b906aec544372568... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: With both Eric's and Serhiy's updates merged, and issue 33039 broken out for the __index__ oddities, this is resolved now. ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- pull_requests: +6428 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: 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/df00f048250b9a07195b0e3b1c5c0161fdc... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +6438 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +6439 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: 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/22df4187c3882c6ec67180902e1151e65b0... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: 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/7488c79b600cd173b0ccea13adb567d078e... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26701> _______________________________________
participants (6)
-
Eric Appelt -
miss-islington
-
Nick Coghlan
-
R. David Murray
-
Robert Smallshire
-
Serhiy Storchaka