gh-146636: PEP 803: Reference documentation#148013
gh-146636: PEP 803: Reference documentation#148013encukou wants to merge 4 commits intopython:mainfrom
Conversation
Doc/whatsnew/3.15.rst
Outdated
|
|
||
| .. _whatsnew315-abi3t: | ||
|
|
||
| :pep:`903`: ``abi3t`` -- Stable ABI for Free-Threaded Builds |
There was a problem hiding this comment.
There seems to be a typo in the documentation: 903should be 803
Doc/whatsnew/3.15.rst
Outdated
| part of the instance struct; and | ||
| - Switching from a ``PyInit_`` function to a new export hook, | ||
| :c:func:`PyModExport_* <PyModExport_modulename>`, introduced for this | ||
| purpose in :pep:`903`. |
There was a problem hiding this comment.
the same here as well : purpose in :pep:803
ZeroIntensity
left a comment
There was a problem hiding this comment.
Congrats on the PEP acceptance :)
Mostly editorial comments from me. The content generally looks good.
| In the :ref:`Stable ABI <stable-abi>` for Free-Threaded Builds (``abi3t``), | ||
| this struct is opaque, and unusable in practice. | ||
| The struct, including all members, is part of Stable ABI for | ||
| non-free-threaded builds (``abi3``). |
There was a problem hiding this comment.
Why is "Free-Threaded Builds" in title case, but then "non-free-threaded builds" isn't?
|
|
||
| .. c:macro:: Py_LIMITED_API | ||
| - ``abi3``, introduced in Pyton 3.2, is compatible with | ||
| **non**-:term:`free threaded <free-threaded build>` builds of CPython. |
There was a problem hiding this comment.
Nitpicky, but I believe "free threaded" needs a dash here. In the original issue where we added the "free-threaded build" term (#144277), we determined that no dash was correct only when "free threaded" was a noun.
| Note that compiling for Stable ABI is *not* a complete guarantee that code will | ||
| be compatible with the expected Python versions. | ||
| Stable ABI prevents *ABI* issues, like linker errors due to missing |
There was a problem hiding this comment.
I think we need to precede "Stable ABI" with "the"?
| Note that compiling for Stable ABI is *not* a complete guarantee that code will | |
| be compatible with the expected Python versions. | |
| Stable ABI prevents *ABI* issues, like linker errors due to missing | |
| Note that compiling for the Stable ABI is *not* a complete guarantee that code will | |
| be compatible with the expected Python versions. | |
| The Stable ABI prevents *ABI* issues, like linker errors due to missing |
| symbols or data corruption due to changes in structure layouts or function | ||
| signatures. | ||
| However, other changes in Python can change the *behavior* of extensions. | ||
| See Python's Backwards Compatibility Policy (:pep:`387`) for details. |
There was a problem hiding this comment.
This sentence confused me a little when I first read it. I had read it as "We might change the behavior of extensions -- go read our backward compatibility policy if you want to know what", but then we provide an example right after the reader was diverted. Could we move this sentence to after the following paragraph, or put it in a seealso note?
| C extensions that target the :ref:`Stable ABI <stable-abi>` can now be | ||
| compiled for the new *Stable ABI for Free-Threaded Builds* (also known | ||
| as ``abi3t``), which makes them compatible with | ||
| :term:`free-threaded build <free-threaded build>` builds of CPython. |
There was a problem hiding this comment.
| :term:`free-threaded build <free-threaded build>` builds of CPython. | |
| :term:`free-threaded <free-threaded build>` builds of CPython. |
Doc/whatsnew/3.15.rst
Outdated
| part of the instance struct; and | ||
| - Switching from a ``PyInit_`` function to a new export hook, | ||
| :c:func:`PyModExport_* <PyModExport_modulename>`, introduced for this | ||
| purpose in :pep:`903`. |
There was a problem hiding this comment.
| purpose in :pep:`903`. | |
| purpose in :pep:`803`. |
| :c:func:`PyModExport_* <PyModExport_modulename>`, introduced for this | ||
| purpose in :pep:`903`. | ||
|
|
||
| Note that Stable ABI does not offer all functionality CPython has to offer. |
There was a problem hiding this comment.
| Note that Stable ABI does not offer all functionality CPython has to offer. | |
| Note that the Stable ABI does not offer all the functionality that CPython has to offer. |
Or if you don't like "the" before "Stable ABI":
| Note that Stable ABI does not offer all functionality CPython has to offer. | |
| Note that Stable ABI does not offer all the functionality that CPython has to offer. |
| be selected in a build tool (such as Setuptools, ``meson-python``, Cython, | ||
| Scikit-build-core, Maturin, and similar). |
There was a problem hiding this comment.
Is it intentional that meson-python is the only package in a code block here?
| be selected in a build tool (such as Setuptools, ``meson-python``, Cython, | ||
| Scikit-build-core, Maturin, and similar). | ||
| At the time of writing this entry, these tools did **not** support ``abi3t``. | ||
| If this is the case for "your" tool, compile for ``cp315t`` separately. |
There was a problem hiding this comment.
Hm, why is "your" in quotes?
| At the time of writing this entry, these tools did **not** support ``abi3t``. | ||
| If this is the case for "your" tool, compile for ``cp315t`` separately. | ||
| If not using a build tool -- or when writing such a tool -- you can select | ||
| ``abi3t`` by setting the macro :c:macro:`!Py_TARGET_ABI3T` as discussed |
There was a problem hiding this comment.
I think it'd be nice if the Py_TARGET_ABI3T were an actual link, because it's not linked anywhere else in this section.
| ``abi3t`` by setting the macro :c:macro:`!Py_TARGET_ABI3T` as discussed | |
| ``abi3t`` by setting the macro :c:macro:`Py_TARGET_ABI3T` as discussed |
|
The new check caught removals: https://github.com/python/cpython/actions/runs/23907059205/job/69719041532?pr=148013 (and on your PR out of everyone's ;-) |
📚 Documentation preview 📚: https://cpython-previews--148013.org.readthedocs.build/