classification
Title: C/API documentation: request for documentation of change to Py_ssize_t* arguments.
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 2.6
process
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: amaury.forgeotdarc, asmodai, georg.brandl, loewis, schiotz
Priority: normal Keywords: patch

Created on 2008-10-15 11:16 by schiotz, last changed 2009-04-29 08:35 by asmodai. This issue is now closed.

Files
File name Uploaded Description Edit
py_ssize_t-note.diff asmodai, 2009-04-25 15:26 Py_ssize_t note idea
Messages (12)
msg74801 - (view) Author: Jakob Schiøtz (schiotz) Date: 2008-10-15 11:16
In general, the Python C/API manual is very careful to document when
changes have occurred in the API, this is really useful information when
writing portable extension modules to be used with different Python
versions.

However, there is a group of changes that are not documented.  In Python
2.5 the Py_ssize_t type was introduced, and a number of functions had
arguments changed from int to Py_ssize_t (a trivial change) or from int*
to Py_ssize_t*.  The latter is an incompatible change on 64-bit
platforms, as int and Py_ssize_t have different size, and this DOES
break extension modules on 64-bit platforms.  For example, the change in
int PySlice_GetIndices breaks the Scientific Python NetCDF module badly.

I suggest that a note is added to the documentation of all functions
taking a Py_ssize_t* argument stating that the type of the argument was
changed in Python 2.5.

Best regards

Jakob
msg74802 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2008-10-15 11:44
I think the Py_ssize_t change is clearly documented in the "What's new"
document:
http://docs.python.org/whatsnew/2.5.html#pep-353-using-ssize-t-as-the-index-type
This paragraph also links to:
http://www.python.org/dev/peps/pep-0353/#doesn-t-this-break-much-code
which happens to mention the incompatibility in the slice API.

Didn't you get any compilation warning?

I suggest to use a newer version of Scientific Python: 2.7 at least uses
Py_ssize_t throughout its code.
msg74803 - (view) Author: Jakob Schiøtz (schiotz) Date: 2008-10-15 12:43
Don't get me wrong:  I am not complaining about the code breakage, it is
unavoidable as long as Python is a developing language.  As you say I
can use newer versions of at least some of the modules.  I just think it
would be nice for developers that occasionally write python modules to
have the information at hand in the C/API manual, since that is where
they will be looking when writing the module.
msg74810 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2008-10-15 19:28
I don't think that we will change the 2.5 manuals anymore; Python 2.5 is
about to see its last bug-fix release.

For 2.6, I suppose contributions would be welcome.
msg74863 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-10-16 21:20
I agree with Martin. Patches are welcome.
msg86524 - (view) Author: Jeroen Ruigrok van der Werven (asmodai) * (Python committer) Date: 2009-04-25 15:03
How does this look as an initial idea?
msg86526 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-04-25 15:06
Why not use .. versionchanged?
msg86528 - (view) Author: Jeroen Ruigrok van der Werven (asmodai) * (Python committer) Date: 2009-04-25 15:26
Pure ignore. Let me adjust the patch. Do we prefer versionchanged before
or after versionadded? I am guessing after versionadded so we get a
better chronological view. Although there's something to be said for a
reverse chronological view too.
msg86533 - (view) Author: Jeroen Ruigrok van der Werven (asmodai) * (Python committer) Date: 2009-04-25 18:00
Committed a first batch in r71910.
msg86536 - (view) Author: Jeroen Ruigrok van der Werven (asmodai) * (Python committer) Date: 2009-04-25 18:47
Fixed the slice stuff in r71915.
msg86555 - (view) Author: Jeroen Ruigrok van der Werven (asmodai) * (Python committer) Date: 2009-04-25 21:18
OK, I went through the entire C API documentation and marked up every
part that changed from int to Py_ssize_t in our documentation.
msg86785 - (view) Author: Jeroen Ruigrok van der Werven (asmodai) * (Python committer) Date: 2009-04-29 08:35
Merged 2.6 and py3k what was appropriate.
History
Date User Action Args
2009-04-29 08:35:54asmodaisetmessages: + msg86785
2009-04-25 21:18:24asmodaisetstatus: open -> closed
resolution: accepted
messages: + msg86555

stage: resolved
2009-04-25 18:47:04asmodaisetmessages: + msg86536
2009-04-25 18:00:30asmodaisetmessages: + msg86533
2009-04-25 15:26:28asmodaisetfiles: + py_ssize_t-note.diff

messages: + msg86528
2009-04-25 15:25:41asmodaisetfiles: - py_ssize_t-note.diff
2009-04-25 15:06:43georg.brandlsetmessages: + msg86526
2009-04-25 15:03:55asmodaisetfiles: + py_ssize_t-note.diff

nosy: + asmodai
messages: + msg86524

keywords: + patch
2008-10-16 21:20:55georg.brandlsetmessages: + msg74863
2008-10-15 19:28:12loewissetnosy: + loewis
messages: + msg74810
2008-10-15 12:43:31schiotzsetmessages: + msg74803
2008-10-15 11:44:12amaury.forgeotdarcsetnosy: + amaury.forgeotdarc
messages: + msg74802
2008-10-15 11:16:16schiotzcreate