C/API documentation: request for documentation of change to Py_ssize_t* arguments.

[schiotz]

BPO	4129
Nosy	@loewis, @birkenfeld, @amauryfa, @ashemedai
Files	py_ssize_t-note.diff: Py_ssize_t note idea

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/birkenfeld'
closed_at = <Date 2009-04-25.21:18:24.014>
created_at = <Date 2008-10-15.11:16:16.179>
labels = ['type-feature', 'docs']
title = 'C/API documentation: request for documentation of change to Py_ssize_t* arguments.'
updated_at = <Date 2009-04-29.08:35:54.827>
user = 'https://bugs.python.org/schiotz'

bugs.python.org fields:

activity = <Date 2009-04-29.08:35:54.827>
actor = 'asmodai'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2009-04-25.21:18:24.014>
closer = 'asmodai'
components = ['Documentation']
creation = <Date 2008-10-15.11:16:16.179>
creator = 'schiotz'
dependencies = []
files = ['13773']
hgrepos = []
issue_num = 4129
keywords = ['patch']
message_count = 12.0
messages = ['74801', '74802', '74803', '74810', '74863', '86524', '86526', '86528', '86533', '86536', '86555', '86785']
nosy_count = 5.0
nosy_names = ['loewis', 'georg.brandl', 'amaury.forgeotdarc', 'schiotz', 'asmodai']
pr_nums = []
priority = 'normal'
resolution = 'accepted'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue4129'
versions = ['Python 2.6']

[schiotz]

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

[amauryfa]

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.

[schiotz]

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.

[loewis]

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.

[birkenfeld]

I agree with Martin. Patches are welcome.

[ashemedai]

How does this look as an initial idea?

[birkenfeld]

Why not use .. versionchanged?

[ashemedai]

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.

[ashemedai]

Committed a first batch in r71910.

[ashemedai]

Fixed the slice stuff in r71915.

[ashemedai]

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.

[ashemedai]

Merged 2.6 and py3k what was appropriate.