classification
Title: Documentation for int constructor mentions __int__ but not __trunc__
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, miss-islington, ncoghlan, r.david.murray, robert_smallshire, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2016-04-06 09:01 by robert_smallshire, last changed 2018-05-10 14:38 by miss-islington. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 6022 merged Eric Appelt, 2018-03-08 03:22
PR 6049 merged miss-islington, 2018-03-10 08:44
PR 6050 merged miss-islington, 2018-03-10 08:45
PR 6054 merged serhiy.storchaka, 2018-03-10 15:02
PR 6055 merged miss-islington, 2018-03-10 15:19
PR 6056 merged miss-islington, 2018-03-10 15:20
PR 6741 merged serhiy.storchaka, 2018-05-09 08:09
PR 6751 merged miss-islington, 2018-05-10 13:39
PR 6752 merged miss-islington, 2018-05-10 13:39
Messages (14)
msg262941 - (view) Author: Robert Smallshire (robert_smallshire) * Date: 2016-04-06 09:01
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.
msg262945 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-04-06 13:53
It is documented in the relevant PEP (pep 3141), but should indeed be added to the appropriate places in the regular documentation.
msg313456 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-03-08 20:06
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__.
msg313514 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-03-10 08:44
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
msg313516 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-03-10 09:03
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__.
msg313531 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-03-10 15:10
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
msg313532 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-03-10 15:10
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
msg313534 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-03-10 15:18
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
msg313536 - (view) Author: miss-islington (miss-islington) Date: 2018-03-10 15:49
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
msg313537 - (view) Author: miss-islington (miss-islington) Date: 2018-03-10 15:55
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
msg313647 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-03-12 13:03
With both Eric's and Serhiy's updates merged, and issue 33039 broken out for the __index__ oddities, this is resolved now.
msg316361 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-05-10 13:38
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
msg316365 - (view) Author: miss-islington (miss-islington) Date: 2018-05-10 14:38
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
msg316366 - (view) Author: miss-islington (miss-islington) Date: 2018-05-10 14:38
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
History
Date User Action Args
2018-05-10 14:38:23miss-islingtonsetmessages: + msg316366
2018-05-10 14:38:09miss-islingtonsetmessages: + msg316365
2018-05-10 13:39:55miss-islingtonsetpull_requests: + pull_request6439
2018-05-10 13:39:09miss-islingtonsetpull_requests: + pull_request6438
2018-05-10 13:38:53ncoghlansetmessages: + msg316361
2018-05-09 08:09:25serhiy.storchakasetpull_requests: + pull_request6428
2018-03-16 11:24:53cheryl.sabellalinkissue21611 superseder
2018-03-12 13:03:01ncoghlansetstatus: open -> closed
resolution: fixed
messages: + msg313647

stage: patch review -> resolved
2018-03-10 15:55:15miss-islingtonsetmessages: + msg313537
2018-03-10 15:49:26miss-islingtonsetnosy: + miss-islington
messages: + msg313536
2018-03-10 15:20:41miss-islingtonsetpull_requests: + pull_request5818
2018-03-10 15:19:42miss-islingtonsetpull_requests: + pull_request5817
2018-03-10 15:18:35serhiy.storchakasetmessages: + msg313534
2018-03-10 15:10:48ncoghlansetmessages: + msg313532
2018-03-10 15:10:39ncoghlansetmessages: + msg313531
2018-03-10 15:02:23serhiy.storchakasetpull_requests: + pull_request5815
2018-03-10 09:03:27ncoghlansetmessages: + msg313516
2018-03-10 08:45:21miss-islingtonsetpull_requests: + pull_request5811
2018-03-10 08:44:23miss-islingtonsetpull_requests: + pull_request5810
2018-03-10 08:44:20ncoghlansetnosy: + ncoghlan
messages: + msg313514
2018-03-08 20:06:11serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg313456
2018-03-08 03:22:33Eric Appeltsetkeywords: + patch
stage: patch review
pull_requests: + pull_request5788
2016-04-06 13:53:46r.david.murraysetnosy: + r.david.murray

messages: + msg262945
versions: + Python 3.6
2016-04-06 09:01:52robert_smallshirecreate