bpo-43795: PEP 652 user documentation #25668
Conversation
Mark up all the version macros, adding them to the index and allowing links to them. Clarify that these are resolved at build time. Add an example for Python 3.10. Some people might assume this is 0x10, not 0xA, based on how well PY_VERSION_HEX "reads" in hex. Link to the (upcoming) page on API and ABI stability.
This replaces the existing :stableabi:, which wasn't really used. Doc/data/stable_abi.dat is expanded to include all relevant info (kind of the symbol and version it was added in), and the c_annotations Sphinx extension reads this file and adds notes similar to ones added by :stableabi: (which wasn't really used). Relevant prior work: #23185 Co-authored-by: Will Ayd <william.ayd@icloud.com>
|
As per the PEP, I added a list of everything in the limited API, as well as notes in individual doc entries. A screenshot of the notes:
|
|
The docs notes will now show platform restrictions, based on
|
|
This looks good to me. I had few nits to clarify. |
|
|
||
| Thus ``3.4.1a2`` is hexversion ``0x030401a2``. | ||
| CPython exposes its version number in the following macros. | ||
| Note that these correspond to the version code is built with, |
willingc
May 7, 2021
Contributor
Perhaps bold part of this sentence re: build version vs run-time version.
| version information can be found by treating it as a 32 bit number in | ||
| the following manner: | ||
|
|
||
| +-------+-------------------------+-------------------------+ |
| (x>=2) on the particular :ref:`platform <stable-abi-platform>`. | ||
|
|
||
| Defining ``Py_LIMITED_API`` to a value of :c:data:`PY_VERSION_HEX` will | ||
| do the same, but allow additional API added up to specified version, |
willingc
May 7, 2021
Contributor
Great improvements to this section. The wording in this item is slightly confusing. Does this mean: It will use the Limited API for this version and later versions. Earlier versions lose compatibility since additional API may exist prior to this version.
encukou
May 7, 2021
Author
Member
Thanks for the note! It really helps to have a second set of eyes here.
I've shuffled the paragraph around; hopefully things are clearer with this order.
|
|
||
| For example, while :c:func:`PyList_GetItem` is available, its “unsafe” macro | ||
| variant :c:func:`PyList_GET_ITEM` is not. | ||
| The macro can be faster because it can rely on version-specific implementation |
|
Thank you for the thoughtful comments! |
b05955d
into
python:main
|
Sorry, I can't merge this PR. Reason: |
|
Thanks @encukou for the PR |
|
GH-26034 is a backport of this pull request to the 3.10 branch. |
|
This can be confusing; more and more often and I need a page to link to. So I merged this. |
Include/README.rstwith a link to a devguide page with the same infohttps://bugs.python.org/issue43795
Automerge-Triggered-By: GH:encukou