PEP 776: Address some of pfmoore's comments (#4310)

Co-authored-by: Hugo van Kemenade <[email protected]>

Author: hoodmane

peps/pep-0776.rst

@@ -652,21 +652,43 @@ packages like aiohttp, Requests, Pydantic, cryptography, and orjson.
 About 60 packages are also testing against Pyodide in their CI, including NumPy,
 pandas, awkward-cpp, scikit-image, statsmodels, PyArrow, Hypothesis, and PyO3.
 
-Emscripten Wheel Format
-~~~~~~~~~~~~~~~~~~~~~~~
+Pyodide Wheel Tags
+~~~~~~~~~~~~~~~~~~
+
+Pyodide wheels will use ``pyodide_<abi>_wasm32`` as the platform tag. For
+example, ``pyodide_2025_0_wasm32``.
+
+With a fixed version of Emscripten, it is possible to link dynamic libraries
+that require a large number of distinct ABIs, depending on ABI-sensitive linker
+options and what versions of what static libraries are linked. It is our intent
+that the ``pyodide_2025_0`` specifies the particular ABI that will work with the
+Pyodide CPython runtime.
+
+For example, wheels with the following tags are compatible with Python 3.13
+Pyodide:
+
+- ``cp13-cp13-pyodide_2025_0_wasm32``
+- ``abi3-cp10-pyodide_2025_0_wasm32``
+
+As well as all non-platformed tags. To generate the list of compatible tags, one
+can use the following code::
 
-Emscripten wheels will use either the format ``emscripten_<version>_wasm32`` or
-``pyodide_<abi>_wasm32``. For example:
 
-* ``emscripten_3_1_58_wasm32``
-* ``pyodide_2025_0_wasm32``
+    from packaging.tags import cpython_tags, _generic_platforms
 
-The first triple is ambiguous, since even with Emscripten 3.1.58 it is possible
-to link dynamic libraries that require a large number of distinct ABIs,
-depending on linker and compiler options. It is our intent that the
-``pyodide_2025_0`` specifies the particular ABI. Thus, the relationship between
-``pyodide_<abi>`` and ``emscripten_<version>`` is intended to be the same as the
-relationship between ``manylinux<version>`` and ``linux``.
+    def _emscripten_platforms() -> Iterator[str]:
+        pyodide_abi_version = sysconfig.get_config_var("PYODIDE_ABI_VERSION")
+        if pyodide_abi_version:
+            yield f"pyodide_{pyodide_abi_version}_wasm32"
+        yield from _generic_platforms()
+
+    emscripten_tags = cpython_tags(platforms=_emscripten_platforms())
+
+This code will be added to `pypa/packaging
+<https://github.com/pypa/packaging/pull/804>`__.
+
+Emscripten Wheel ABI
+~~~~~~~~~~~~~~~~~~~~
 
 The specification of the ``pyodide_<abi>`` ABI includes:
 
@@ -682,16 +704,45 @@ compiler and passing appropriate compiler and linker flags. It is possible for
 other people to build their own Python interpreter that is compatible with the
 Pyodide ABI, it is not necessary to use the Pyodide distribution itself.
 
-The ``pyodide build`` tool knows how to create wheels that match our ABI. As an
-alternative,
-`the auditwheel-emscripten tool <https://github.com/ryanking13/auditwheel-emscripten>`__
-is capable of performing basic compatibility checks, vendoring shared libraries,
-and retagging the wheel from ``emscripten_<version>`` to ``pyodide_<abi>``. Unlike
-with manylinux, there is no need for a Docker container to build the
+The ``pyodide build`` tool knows how to create wheels that match our ABI. Unlike
+with manylinux wheels, there is no need for a Docker container to build the
 ``pyodide_<abi>`` wheels. All that is needed is a Linux machine and appropriate
 versions of Python, Node.js, and Emscripten.
 
 
+Package Installers
+~~~~~~~~~~~~~~~~~~
+
+Installers should use the ``_emscripten_platforms()`` function shown above to
+determine which platforms are compatible with an Emscripten build of CPython. In
+particular, the Pyodide ABI version is exposed via
+``sysconfig.get_config_var("PYODIDE_ABI_VERSION")``.
+
+
+Package indexes
+~~~~~~~~~~~~~~~
+
+We recommend that package indexes accept any wheel whose platform tag matches
+``pyodide_[0-9]+_[0-9]+_wasm32``. We recommend that package indexes continue not
+accepting wheels that match ``emscripten_[0-9]+_[0-9]+_[0-9]+_wasm32``.
+
+
+Dependency Specifier Markers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To check for the Emscripten platform in a dependency specifier, one can use
+``sys_platform == 'emscripten'`` (or its negation). Such checks are already in use
+in the wild and seem to be sufficient for the needs of the community.
+
+
+Trove Classifier
+~~~~~~~~~~~~~~~~
+
+Packages that build and test Emscripten wheels can declare this by adding the
+``Environment :: WebAssembly :: Emscripten``. PyPI already accepts uploads of
+packages with this classifier.
+
+
 PEP 11
 ------
 
@@ -786,7 +837,8 @@ partially-upstreamed features so that Pyodide can replace them with more
 complete versions downstream.
 
 These backwards compatibility concerns impact not just the runtime but also the
-packaging system.
+packaging system. Adding new platform tags should not affect existing packaging
+tools because tools ignore wheels with an unknown package tag.
 
 
 Security Implications
@@ -809,8 +861,11 @@ to use them all at runtime. The documentation will cover this in a similar form
 to the existing Windows embeddable package. In the short term, we will encourage
 developers to use Pyodide if at all possible.
 
-Second, developers of packages with binary components need to know how to build
-and release them for Emscripten (see Packaging).
+Second, maintainers of packages with binary components need to know how to
+build, test, label, and deploy them for Emscripten (see Packaging). The Pyodide
+documentation on `building and testing packages
+<https://pyodide.org/en/stable/development/building-and-testing-packages.html>`__
+is the best reference for this.
 
 
 Reference Implementation