Bare .so for abi3.abi3t

plus light editing

Author: encukou

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.
@@ -288,20 +288,6 @@ The tag ``abi3t`` is chosen to reflect the fact that this ABI is similar to
 uses the letter ``t`` in existing, version-specific ABI tags like ``cp314t``).
 
 
-Filename tag
-------------
-
-On systems that use the ``abi3`` tag in filenames, a new filename tag
-(``abi3t``) is added so that older stable ABI extensions
-(:samp:`{name}.abi3.so`) can be installed in the same directory as ones that
-support Stable ABI for free-threaded Python (:samp:`{name}.abi3t.so`).
-
-There can only be one ABI tag in a filename (there is no concept of "compressed
-tag sets like in wheel tags), so extensions that are compatible with both ABIs
-at once need to use *one* of the tags -- the new one (``abi3t``), which
-is currently unused.
-
-
 Specification
 =============
 
@@ -484,29 +470,27 @@ 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 that support free-threading should instead use ``abi3t.so``.
-This includes extensions compatible with *both* ``abi3`` and ``abi3t``.
-
-On these systems, all builds of CPython -- GIL-enabled and free-threaded --
-will load extensions with the ``abi3t`` tag.
-Free-threaded builds will -- unlike in 3.14 -- *not* load extensions
-with the ``abi3`` tag.
-If files are present with both tags, GIL-enabled builds will prefer
-"their" ``*.abi3.so`` over ``*.abi3t.so``.
-
-Put another way, ``importlib.machinery.EXTENSION_SUFFIXES`` will be
-(for ``x86_64-linux-gnu`` builds of CPython):
-
-* ``python3.15``:
-  ``['.cpython-315-x86_64-linux-gnu.so', '.abi3.so', '.abi3t.so', '.so']``
-* ``python3.15t``:
+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.
@@ -526,25 +510,29 @@ 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.
 
-In both cases, if a resulting extension's *filename* would use the ``abi3``
-tag (that is, :samp:`{modulename}.abi3.so` on Linux, macOS, and similar),
-the ``abi3t`` tag should be used instead (that is,
-:samp:`{modulename}.abi3t.so` on those systems).
-If this tag is not used, there should be no change. (This is always the case
-on Windows, where the filename should remain :samp:`{name}.pyd`.)
-
 .. _compressed tag set: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#compressed-tag-sets
 
 The version of the Stable ABI, both ``abi3`` and ``abi3t``, is indicated by
@@ -685,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      |
@@ -761,7 +749,8 @@ This PEP combines several pieces, implemented individually:
   `python/cpython#137212 <https://github.com/python/cpython/pull/137212>`__.
 - A check for older ``abi3`` was implemented in GitHub pull request
   `python/cpython#137957 <https://github.com/python/cpython/pull/137957>`__.
-- For wheel tags, there is no implementation yet.
+- For wheel tags, a draft pull request is at
+  `pypa/packaging/pull#1099 <https://github.com/pypa/packaging/pull/1099>`__.
 - A porting guide is not yet written.
 
 
@@ -836,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
 -------------------------------------------------
 
@@ -859,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
 =========