[issue15465] Improved documentation for C API version info
New submission from Nick Coghlan <ncoghlan@gmail.com>: 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 ---------- assignee: docs@python components: Documentation messages: 166546 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Improved documentation for C API version info type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- versions: +Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________
Kushal Das added the comment: Attaching patch with the initial documentation of the macros. It also fixes the typo in the title of stable API section. ---------- keywords: +patch nosy: +kushaldas Added file: http://bugs.python.org/file29258/issue15465.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________
Kushal Das added the comment: Adding the updated patch with changes as suggested in the review ---------- Added file: http://bugs.python.org/file29260/issue15465v2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________
Kushal Das added the comment: version 3 of the patch where sys.hexversion table is moved and now a link to api and abi versioning given. ---------- Added file: http://bugs.python.org/file29277/issue15465v3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________
Changes by Kushal Das <kushaldas@gmail.com>: Added file: http://bugs.python.org/file29313/issue15465v4.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________
Kushal Das added the comment: version 4 of the patch contains a new column in table as Bytes as suggested by Ezio Melotti ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________
Nick Coghlan added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________
Kushal Das added the comment: Attached version 5 of the patch with changes based on suggestions of ncoghlan ---------- Added file: http://bugs.python.org/file29321/issue15465v5.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________
participants (3)
-
Kushal Das -
Nick Coghlan
-
Roundup Robot