[issue12965] longobject: documentation improvements

[Stefan Krah]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Stefan Krah]

Stefan Krah  added the comment:

OK, I'll see if I find some time for the 2.7 docs.

--
assignee:  -> skrah

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Mark Dickinson]

Mark Dickinson  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Roundup Robot]

Roundup Robot  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Roundup Robot]

Roundup Robot  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Roundup Robot]

Roundup Robot  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Stefan Krah]

Stefan Krah  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Mark Dickinson]

Mark Dickinson  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Mark Dickinson]

Mark Dickinson  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Roundup Robot]

Roundup Robot  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Stefan Krah]

Changes by Stefan Krah :


--
assignee: docs@python -> mark.dickinson

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12965] longobject: documentation improvements

[Stefan Krah]

New submission from Stefan Krah :

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com