[issue12965] longobject: documentation improvements
New submission from Stefan Krah <stefan-usenet@bytereef.org>: I think the integer objects documentation could be clearer on a couple of points: - Despite being listed under "Concrete Objects Layer", some functions implicitly accept anything with an __int__() method. Currently only the PyLong_AsLong() documentation states this explicitly. The patch clearly distinguishes between functions that duck type and functions that don't. - The patch replaces "is greater than *_MAX" instances with "out of bounds" to include the other error condition "is less than *_MIN". Additionally, the patch fixes comments in longobject.c that don't state the duck typing behavior. ---------- assignee: docs@python components: Documentation files: longobject-doc.diff keywords: patch messages: 143922 nosy: docs@python, mark.dickinson, skrah priority: normal severity: normal stage: patch review status: open title: longobject: documentation improvements type: feature request versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file23133/longobject-doc.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Changes by Stefan Krah <stefan-usenet@bytereef.org>: ---------- assignee: docs@python -> mark.dickinson _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset d4839fea4a5a by Mark Dickinson in branch 'default': Issue #12965: Fix some inaccurate comments in Objects/longobject.c. Thanks Stefan Krah. http://hg.python.org/cpython/rev/d4839fea4a5a ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Mark Dickinson <dickinsm@gmail.com> added the comment: I've fixed some of the inaccurate comments in Objects/longobject.c, for the default branch; I'm still looking at the Doc update. This really is a bit of a mess, especially for cases like PyLong_AsVoidPtr, which can either end up calling PyLong_As(Long)Long (which allows conversion via __int__), or PyLong_AsUnsigned(Long)Long (which doesn't). Ultimately, I think it would make sense to remove all __int__ conversions from Objects/longobject.c; this would affect: - PyLong_AsLongAndOverflow - PyLong_AsLong - PyLong_AsUnsignedLongMask and the 'LongLong' variants of these. The ramifications of such a change might be quite long-reaching; in particular, I seem to recall that this would affect the 'getargs' machinery. It could be fun to remove these conversions and see how much of the test-suite fails. :-) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Mark Dickinson <dickinsm@gmail.com> added the comment:
It could be fun to remove these conversions and see how much of the test-suite fails. :-)
... On my machine, just test_ctypes and test_getargs2, as it turns out. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Stefan Krah <stefan-usenet@bytereef.org> added the comment:
Ultimately, I think it would make sense to remove all __int__ conversions from Objects/longobject.c;
+1 I think this API cleanup is worth some (probably very limited) breakage in third party modules. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset 5ca9a51f3d85 by Mark Dickinson in branch '3.2': Issue #12965: Clean up C-API docs for PyLong_AsLong(AndOverflow); clarify that __int__ will be called for non-PyLongs http://hg.python.org/cpython/rev/5ca9a51f3d85 New changeset 63fc1552cd36 by Mark Dickinson in branch 'default': Issue #12965: Merge from 3.2 http://hg.python.org/cpython/rev/63fc1552cd36 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset 3ace8e17074a by Mark Dickinson in branch '3.2': Issue #12965: Clean up C-API docs for PyLong_AsLongLong(AndOverflow); clarify that __int__ will be called for non-PyLongs http://hg.python.org/cpython/rev/3ace8e17074a New changeset 85683f005fc8 by Mark Dickinson in branch 'default': Issue #12965: Merge from 3.2. http://hg.python.org/cpython/rev/85683f005fc8 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset e1416a4d728a by Mark Dickinson in branch '3.2': Issue #12965: More PyLong_As* clarifications. Thanks Stefan Krah. http://hg.python.org/cpython/rev/e1416a4d728a New changeset 349bc58e8c66 by Mark Dickinson in branch 'default': Issue #12965: Merge from 3.2. http://hg.python.org/cpython/rev/349bc58e8c66 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Mark Dickinson <dickinsm@gmail.com> added the comment: Docs mostly fixed now for Python 3.2 and Python 3.3. That leaves 2.7, where there are some additional complications (e.g., __long__ in addition to __int__, when / whether short ints are accepted, etc.). While it would be good to fix the 2.7 docs as well, I don't see myself having time for this in the near future, so I'm unassigning for now; Stefan, I think should feel free to take this issue and check in clarifications for 2.7, if you want to. ---------- assignee: mark.dickinson -> versions: -Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Stefan Krah <stefan-usenet@bytereef.org> added the comment: OK, I'll see if I find some time for the 2.7 docs. ---------- assignee: -> skrah _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
Stefan Krah added the comment: This seems like too much trouble for 2.7. Closing, since I was the one who opened the issue (just reopen if you think it is still worth it). ---------- assignee: skrah -> resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________
participants (3)
-
Mark Dickinson -
Roundup Robot
-
Stefan Krah