classification
Title: longobject: documentation improvements
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: docs@python, mark.dickinson, python-dev, skrah
Priority: normal Keywords: patch

Created on 2011-09-12 16:57 by skrah, last changed 2014-10-14 14:38 by skrah. This issue is now closed.

Files
File name Uploaded Description Edit
longobject-doc.diff skrah, 2011-09-12 16:57 review
Messages (11)
msg143922 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2011-09-12 16:57
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.
msg146251 - (view) Author: Roundup Robot (python-dev) Date: 2011-10-23 19:47
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
msg146252 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2011-10-23 19:55
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. :-)
msg146253 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2011-10-23 20:14
> 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.
msg148797 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2011-12-03 12:35
> 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.
msg163566 - (view) Author: Roundup Robot (python-dev) Date: 2012-06-23 09:50
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
msg163571 - (view) Author: Roundup Robot (python-dev) Date: 2012-06-23 10:15
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
msg163578 - (view) Author: Roundup Robot (python-dev) Date: 2012-06-23 11:13
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
msg163579 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2012-06-23 11:18
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.
msg163642 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2012-06-23 16:40
OK, I'll see if I find some time for the 2.7 docs.
msg229293 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2014-10-14 14:38
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).
History
Date User Action Args
2014-10-14 14:38:34skrahsetstatus: open -> closed
messages: + msg229293

assignee: skrah ->
resolution: fixed
stage: patch review -> resolved
2012-06-23 16:40:14skrahsetassignee: skrah
messages: + msg163642
2012-06-23 11:18:55mark.dickinsonsetassignee: mark.dickinson -> (no value)
messages: + msg163579
versions: - Python 3.1
2012-06-23 11:13:43python-devsetmessages: + msg163578
2012-06-23 10:15:13python-devsetmessages: + msg163571
2012-06-23 09:50:08python-devsetmessages: + msg163566
2011-12-03 12:35:16skrahsetmessages: + msg148797
2011-10-23 20:14:39mark.dickinsonsetmessages: + msg146253
2011-10-23 19:55:01mark.dickinsonsetmessages: + msg146252
2011-10-23 19:47:52python-devsetnosy: + python-dev
messages: + msg146251
2011-09-12 16:58:18skrahsetassignee: docs@python -> mark.dickinson
2011-09-12 16:57:49skrahcreate