DOC: improve docs for limited api builds - #885
Conversation
rgommers
left a comment
rgommers
left a comment
There was a problem hiding this comment.
Thanks @ngoldbaum for writing docs for the Limited API! Overall this content looks like a great start. My main comment right now is that it's not in the right places: it can't be in the reference guide, and the examples section of the "Passing arguments to Meson" page also feels wrong. I think we need a new page, as a how-to under "Using shared libraries" called something like "Using the Limited C API" or some such title.
This content, put together in a single page, will be a great start. I have a few things I'd like to add, like how to set it up as opt-in (e.g., as in PyWavelets/pywt#828).
We can then also address a couple of open issues: gh-624, some parts of gh-787.
| sufficient to compile the extension modules for ``abi3t`` when | ||
| building with free-threaded CPython 3.15 or later. Building | ||
| ``abi3t`` extension modules with a GIL-enabled interpreter is not | ||
| supported, see `Meson issue 15637`_. |
There was a problem hiding this comment.
Let's just say "not supported yet". We don't link issues from the docs, and there isn't much of interest to see anyway in that issue for the average user.
| value ``abi3`` is used for the Python wheel filename ABI tag. | ||
| Python wheel filename ABI tag is set to the stable ABI tag: | ||
| ``abi3`` when building with GIL-enabled CPython, and ``abi3.abi3t`` | ||
| when building with free-threaded CPython 3.15 or later, see below. |
There was a problem hiding this comment.
We want to keep the reference guide content very short and to the point. The above three sentences are enough on this page I'd say. Then reference the detailed docs for more info. That's where the below content should move.
|
I rearranged with a new howto guide page. Let me know what you think. |
dnicolodi
left a comment
dnicolodi
left a comment
There was a problem hiding this comment.
Just a few quick remarks. I find the content in the new howto page hard to read, mostly because there are things repeated several times with different language and because the content is not presented at increasing level of detail but zooming in and out constantly. The other are minor comments. Please squash the commits into just one commit.
| A boolean indicating whether the extension modules contained in the | ||
| Python package target the `Python limited API`_. Extension | ||
| modules can be compiled for the Python limited API specifying the |
There was a problem hiding this comment.
This paragraph should be kept.
| Python package target the `Python limited API`_. Extension modules | ||
| can be compiled for the Python limited API specifying the | ||
| ``limited_api`` argument to the |extension_module()|_ function in the | ||
| Meson Python module. When this setting is set to true, the Python |
There was a problem hiding this comment.
Please avoid whitespace only changes.
| wheel filename ABI tag is set to the stable ABI tag: ``abi3`` when | ||
| building with GIL-enabled CPython, and ``abi3.abi3t`` when building | ||
| with free-threaded CPython 3.15 or later. Free-threaded CPython before | ||
| 3.15 does not support the limited API, so this setting must be | ||
| disabled at build time for those interpreter versions. See | ||
| :ref:`howto-limited-api` for more details and examples. |
There was a problem hiding this comment.
I think this is too detailed: the description of options should be as concise as possible.
| wheel filename ABI tag is set to the stable ABI tag: ``abi3`` when | |
| building with GIL-enabled CPython, and ``abi3.abi3t`` when building | |
| with free-threaded CPython 3.15 or later. Free-threaded CPython before | |
| 3.15 does not support the limited API, so this setting must be | |
| disabled at build time for those interpreter versions. See | |
| :ref:`howto-limited-api` for more details and examples. | |
| wheel filename ABI tag is set to ``abi3`` or ``abi3.abi3t`` when | |
| the build targets a Python interpreter supporting the free-threaded | |
| stable ABI. See :ref:`howto-limited-api` for details. |
| otherwise. This setting has no effect on the wheel tag when building | ||
| with PyPy. |
There was a problem hiding this comment.
| otherwise. This setting has no effect on the wheel tag when building | |
| with PyPy. | |
| otherwise. PyPy does not support the limited API thus this setting has | |
| no effect when building with PyPy. |
| with free-threaded CPython 3.15 or later. Building ``abi3t`` extension | ||
| modules with a GIL-enabled interpreter is not supported yet. | ||
|
|
||
| ``abi3t`` requires targeting limited API version 3.15 or later, |
There was a problem hiding this comment.
This is now stated in three different ways. Please find a way to make the content easier to follow.
|
@dnicolodi thanks! I've applied your suggestions. I also rearranged the howto page and I think it's clearer now. |
| A boolean indicating whether the extension modules contained in the | ||
| Python package target the `Python limited API`_. Extension | ||
| modules can be compiled for the Python limited API specifying the |
3 participants
I'm planning to add a section on meson-python abi3t builds in the free-threaded guide. See Quansight-Labs/free-threaded-compatibility#341 which has a stub for meson-python right now.
Ideally I'd like this section to be brief and mostly be linking to the meson-python docs.
I noticed that #856 didn't have any docs and the existing docs on limited API builds are a little thin. Since abi3t adds complexity and some issues for builds on 3.14, I think it's worth adding some more docs.
Let me know if you'd prefer I trim this down some or otherwise do this differently.