diff --git a/peps/pep-0803.rst b/peps/pep-0803.rst index c44cf0b78f6..9e823ccf4cc 100644 --- a/peps/pep-0803.rst +++ b/peps/pep-0803.rst @@ -16,7 +16,7 @@ Abstract ======== Add a new variant of the Stable ABI, called “Stable ABI for Free-Threaded -Python” (or ``abi3t`` for short), and a corresponding API limitations. +Python” (or ``abi3t`` for short). ``abi3t`` will be based on the existing Stable ABI (``abi3``), but make the :c:type:`PyObject` structure opaque. @@ -461,18 +461,36 @@ and may be removed in future CPython versions, if the internal object layout needs to change. -The ``abi3t`` wheel tag ------------------------ +The ``abi3t`` wheel and filename tags +------------------------------------- Wheels that use a stable ABI compatible with free-threading CPython builds should use a new `ABI tag`_: ``abi3t``. .. _ABI tag: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#abi-tag +On systems where filenames of Stable ABI extensions end with ``.abi3.so``, +extensions compatible with ``abi3t`` should instead use ``.abi3t.so``. +Extensions compatible with *both* ``abi3`` and ``abi3t`` should not use +a tag; they sould end in ``.so`` only. + +On these systems, free-threaded builds of CPython will load extensions +with the ``abi3t`` tag. + +For example, for ``x86_64-linux-gnu`` builds of CPython, +``importlib.machinery.EXTENSION_SUFFIXES`` will be: + +* for ``python3.15``: + ``['.cpython-315-x86_64-linux-gnu.so', '.abi3.so', '.so']`` +* for ``python3.15t``: + ``['.cpython-315-x86_64-linux-gnu.so', '.abi3t.so', '.so']`` + + Recommendations for installers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Package installers should treat this tag as completely separate from ``abi3``. +Package installers should treat the ``abi3t`` tag as completely separate +from ``abi3``. They should allow ``abi3t``-tagged wheels for free-threaded builds wherever they currently allow ``abi3``-tagged ones for (otherwise equal) non-free-threaded builds. @@ -492,14 +510,25 @@ Stable ABI (``abi3``): - defining ``Py_GIL_DISABLED`` (on Windows) - building with free-threaded CPython headers (elsewhere) - Such extensions should be tagged with the `compressed tag set`_ - ``abi3.abi3t``. + The filename of the resulting extension should not have a :pep:`3149` + tag: it should be named :samp:`{modulename}.so`, :samp:`{modulename}.pyd` + or similar. + + Wheels with such extensions should be tagged with the + `compressed tag set`_ ``abi3.abi3t``. - Compile extensions compatible with *only* ``abi3t``, by defining only :samp:`Py_TARGET_ABI3T={v}` and tagging the result with ``abi3t``. This will initially offer no advantages over the ``abi3.abi3t`` option above, but there is a possibility that it will become useful in the future. + On systems that use the :pep:`3149` tag ``abi3`` tag (e.g. on Linux, macOS, + and similar, which use :samp:`{modulename}.abi3.so`), + such extensions should use the tag ``abi3t`` (that is, the extension should + be named :samp:`{modulename}.abi3t.so` on those systems). + + Wheels with such extensions should be tagged with the ABI tag ``abi3t``. + In the above, :samp:`{v}` stands for a the lowest Python version with which the extension should be compatible, in :c:func:`Py_PACK_VERSION` format. In the cases above, this version must be set to 3.15 or higher. @@ -644,7 +673,7 @@ free-threaded one. (*): Wheels with these tags cannot be built; see table below The following table summarizes which wheel tag should be used for an extension -built with a given interpreter and ``Py_LIMITED_API`` macro: +built with the given interpreter and defined macros: +-----------------------+-------------+--------------------+---------------------+-----------+ | To get the wheel tag… | Compile on… | ``Py_LIMITED_API`` | ``Py_TARGET_ABI3T`` | Note | @@ -720,7 +749,8 @@ This PEP combines several pieces, implemented individually: `python/cpython#137212 `__. - A check for older ``abi3`` was implemented in GitHub pull request `python/cpython#137957 `__. -- For wheel tags, there is no implementation yet. +- For wheel tags, a draft pull request is at + `pypa/packaging/pull#1099 `__. - A porting guide is not yet written. @@ -783,15 +813,8 @@ Naming this ``abi4`` Instead of ``abi3t``, we could “bump the version” and use ``abi4`` instead. The difference is largely cosmetic. -However, one thing this PEP does not propose is changing the *filename* -tag: extensions will be named with the extensions like ``.abi3.so``. -Changing this while keeping compatibility with GIL-enabled builds would be -an unnecessary technical change. - -Using ``abi3.abi4`` in wheel tags but only ``.abi3`` in filenames would -look more inconsistent than ``abi3.abi3t`` and ``.abi3``. - -If we added an ``abi4`` tag, the ``Py_LIMITED_API`` value would either need to: +If we added an ``abi4`` tag, the value of the opt-in macro (``Py_TARGET_ABI4`` +or ``Py_LIMITED_API`` or some such) would either need to: * change to start with ``4`` to match ``abi4``, but no longer correspond to ``PY_VERSION_HEX`` (making it harder to generate and check), or @@ -802,6 +825,24 @@ better as a transitional state before larger changes like :pep:`809`'s ``abi2026``. +``abi3+abi3t`` filename tag +--------------------------- + +Extensions that are compatible with both ``abi3`` and ``abi3t`` can +use a "compressed tag set" (``abi3.abi3t``) in wheel metadata, +but not in filenames (``.abi3.so``/``.abi3t.so``). + +We could add a dedicated tag for the combination -- for example, +``.abi3+abi3t.so`` -- but this would have no practical benefits over +omitting the tag altogether -- that is, using bare ``.so``. +Specifically, bare ``.so`` meets the needs of :pep:`3149` (which introduced +the filename tags): existing stable ABI extensions (``.abi3.so``) +and version-specific ABI extensions (``.cpNN-*.so``) can be installed +alongside the ``.so`` file, and will be preferred by interpreters that can +load them. + + + Reusing ``Py_GIL_DISABLED`` to enable the new ABI ------------------------------------------------- @@ -825,6 +866,28 @@ the ability to build for the GIL-only Stable ABI with no source changes was deemed to be worth an extra configuration macro (``Py_TARGET_ABI3T``). +Making ``abi3t`` compatible with GIL-enabled builds +--------------------------------------------------- + +Initially, ``abi3t`` will be compatible with ``abi3``. +It would be possible to promise that it will always be so. +This would make the ``abi3.abi3t`` tag unnecessary; +``abi3t`` could be used instead. + +In this case, installers would need to allow ``abi3t``-tagged wheels +for GIL-enabled builds of Python, needing a change in installers. +Since installers written in Python typically use/vendor the :pypi:`packaging` +library, this change would mostly be limited to one repository. + +The wheel tag ``abi3.abi3t`` would be valid in this scenario; +it could be used to support existing installers (which "know about" ``abi3`` +but not ``abi3t``), to experiment with supporting Python 3.14, and in similar +cases. + +However, this would prevent the possibility of ever making ``abi3`` +and ``abi3t`` diverge. + + Copyright =========