classification
Title: Improved documentation for C API version info
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, kushal.das, ncoghlan, python-dev
Priority: normal Keywords: patch

Created on 2012-07-27 07:05 by ncoghlan, last changed 2013-03-07 13:45 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
issue15465.patch kushal.das, 2013-02-27 06:05 patch to add c-api version macros review
issue15465v2.patch kushal.das, 2013-02-27 10:31 patch to add c-api version macros v2 review
issue15465v3.patch kushal.das, 2013-02-28 07:06 patch to add c-api version macros v3 review
issue15465v4.patch kushal.das, 2013-03-05 11:01 patch to add c-api version macros v4 review
issue15465v5.patch kushal.das, 2013-03-06 04:10 patch to add c-api version macros v5 review
Messages (8)
msg166546 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-07-27 07:05
As far as I can tell, the only mentions of the C API version macros are:

1. In the prose for the stable ABI section (incidentally: this section has a typo in the title)

2. In the documentation for sys.hexversion

There should be a clear "API and ABI Versioning" section in the C API docs that covers:

PY_LIMITED_API
PY_HEX_VERSION
PY_MAJOR_VERSION
PY_MINOR_VERSION
PY_MICRO_VERSION
PY_RELEASE_LEVEL
PY_RELEASE_SERIAL
msg183113 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2013-02-27 06:05
Attaching patch with the initial documentation of the macros. It also fixes the typo in the title of stable API section.
msg183130 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2013-02-27 10:31
Adding the updated patch with changes as suggested in the review
msg183207 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2013-02-28 07:06
version 3 of the patch where sys.hexversion table is moved and now a link to api and abi versioning given.
msg183519 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2013-03-05 11:04
version 4 of the patch contains a new column in table as Bytes as suggested by Ezio Melotti
msg183574 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-03-06 02:42
Mostly looks good to me, but the second sentence in the first paragraph of the new section should be deleted. The relationship between PY_LIMITED_API and PY_VERSION_HEX is already covered in the stable ABI docs:

"""In some cases, the stable ABI needs to be extended with new functions. Extensions modules wishing to use these new APIs need to set Py_LIMITED_API to the PY_VERSION_HEX value of the minimum Python version they want to support (e.g. 0x03030000 for Python 3.3). Such modules will work on all subsequent Python releases, but fail to load (because of missing symbols) on the older releases."""

(As a separate issue, it may be worth doing an editing pass on the stable ABI docs - there are a few typos in there, and the layout is a bit odd for a reference doc. We shouldn't hold up this patch for that, though).
msg183578 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2013-03-06 04:10
Attached version 5 of the patch with changes based on suggestions of ncoghlan
msg183659 - (view) Author: Roundup Robot (python-dev) Date: 2013-03-07 13:45
New changeset adeafab9a18f by Nick Coghlan in branch '3.3':
Close #15465: Document C API version macros
http://hg.python.org/cpython/rev/adeafab9a18f

New changeset a1373861f62f by Nick Coghlan in branch 'default':
Merge fix for #15465 from 3.3
http://hg.python.org/cpython/rev/a1373861f62f
History
Date User Action Args
2013-03-07 13:45:14python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg183659

resolution: fixed
stage: needs patch -> resolved
2013-03-06 04:10:23kushal.dassetfiles: + issue15465v5.patch

messages: + msg183578
2013-03-06 02:42:54ncoghlansetmessages: + msg183574
2013-03-05 11:04:12kushal.dassetmessages: + msg183519
2013-03-05 11:01:03kushal.dassetfiles: + issue15465v4.patch
2013-02-28 07:06:04kushal.dassetfiles: + issue15465v3.patch

messages: + msg183207
2013-02-27 10:31:25kushal.dassetfiles: + issue15465v2.patch

messages: + msg183130
2013-02-27 06:05:18kushal.dassetfiles: + issue15465.patch

nosy: + kushal.das
messages: + msg183113

keywords: + patch
2012-07-27 07:05:35ncoghlansetversions: + Python 3.2, Python 3.3
2012-07-27 07:05:24ncoghlancreate