From 180b08ce0f6df5addaba083c54a646756e01780b Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Mon, 16 Mar 2026 22:55:14 +0100 Subject: [PATCH 1/2] PEP 783: Clarify that PyEmscripten platform is independent of Python And of Python version. Also adjust wording: prefer "Platform" over "ABI" in most places. --- peps/pep-0783.rst | 80 +++++++++++++++++++++++++---------------------- 1 file changed, 43 insertions(+), 37 deletions(-) diff --git a/peps/pep-0783.rst b/peps/pep-0783.rst index a07387ab2fb..6abe44cc238 100644 --- a/peps/pep-0783.rst +++ b/peps/pep-0783.rst @@ -71,7 +71,7 @@ benefit to being able to update the ABI. In order to balance the ABI stability needs of package maintainers with the ABI flexibility to allow the platform to move forward, Pyodide plans to adopt a new -ABI for each feature release of Python which we call +Emscripten platform for each feature release of Python which we call ``pyemscripten_${YEAR}_${PATCH}``. The Pyodide team also coordinates the ABI flags that Pyodide uses with the @@ -99,44 +99,48 @@ The platform tags will take the form: Each one of these will be used with a specified Python version. For example, the platform tag ``pyemscripten_2026_0`` will be used with Python 3.14. -Emscripten Wheel ABI --------------------- +The PyEmscripten Platform +------------------------- -The specification of the ``pyemscripten_`` platform includes: +The specification of the ``pyemscripten_${YEAR}_${PATCH}`` platform includes: * Which version of the Emscripten compiler is used -* What libraries are statically linked with the interpreter +* What libraries are statically linked to the binary * What stack unwinding ABI is to be used * How the loader handles dependency lookup * That libraries cannot use ``-pthread`` * That libraries should be linked with ``-sWASM_BIGINT`` -The ABI is selected by choosing the appropriate version of the Emscripten -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 platform is selected by choosing the appropriate version of the Emscripten +compiler and passing appropriate compiler and linker flags. -The Pyodide ABIs are fully specified in the `Pyodide Platform ABI -`__ documentation. +The platform definition does not include anything about Python and in particular +it is agnostic to the Python version it is intended to be used with. However, +for clarity we will note in the platform documentation which Python version we +plan to use each platform with. -The ``pyodide build`` tool knows how to create wheels that match the Pyodide -ABI. Unlike with manylinux wheels, there is no need for a Docker container to -build the ``pyemscripten_`` wheels. All that is needed is a Linux machine and -appropriate versions of Python, Node.js, and Emscripten. +The PyEmscripten platforms are fully specified in +`Pyodide's documentation on the PyEmscripten Platform `__. -It is possible to validate a wheel by installing and importing it into the +The ``pyodide build`` tool knows how to create wheels that are compatible with the +PyEmscripten platform. Unlike with manylinux wheels, there is no need for a +Docker container to build ``pyemscripten`` wheels. All that is needed is a Linux +machine and appropriate versions of Python, Node.js, and Emscripten. + +It is possible to validate that a wheel is compatible with the PyEmscripten +platform by installing and importing it into an appropriate version of the Pyodide runtime. Because Pyodide can run in an environment with strong sandboxing guarantees, doing this produces no security risks. -Determining the ABI version ---------------------------- +Determining the PyEmscripten Platform Version +--------------------------------------------- -The ABI version is stored in the ``PYEMSCRIPTEN_ABI_VERSION`` config variable -and can be determined via: +The PyEmscripten platform version is stored in the +``PYEMSCRIPTEN_PLATFORM_VERSION`` config variable and can be determined via: .. code-block:: python - pyemscripten_abi_version = sysconfig.get_config_var("PYEMSCRIPTEN_ABI_VERSION") + pyemscripten_platform_version = sysconfig.get_config_var("PYEMSCRIPTEN_PLATFORM_VERSION") To generate the list of compatible tags, one can use the following code: @@ -146,9 +150,9 @@ To generate the list of compatible tags, one can use the following code: from packaging.tags import cpython_tags, _generic_platforms def _emscripten_platforms() -> Iterator[str]: - pyemscripten_abi_version = sysconfig.get_config_var("PYEMSCRIPTEN_ABI_VERSION") - if pyemscripten_abi_version: - yield f"pyemscripten_{pyemscripten_abi_version}_wasm32" + pyemscripten_platform_version = sysconfig.get_config_var("PYEMSCRIPTEN_PLATFORM_VERSION") + if pyemscripten_platform_version: + yield f"pyemscripten_{pyemscripten_platform_version}_wasm32" yield from _generic_platforms() emscripten_tags = cpython_tags(platforms=_emscripten_platforms()) @@ -162,8 +166,8 @@ 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 ABI version is exposed via -``sysconfig.get_config_var(" PYEMSCRIPTEN_ABI_VERSION")``. +particular, the PyEmscripten platform version is exposed via +``sysconfig.get_config_var("PYEMSCRIPTEN_PLATFORM_VERSION")``. Package Indexes --------------- @@ -219,20 +223,21 @@ Alternative Options for the Platform Tag ``pyemscripten`` platform has nothing specifically to do with Python and indeed can be used by any program that uses the appropriate version of Emscripten and the appropriate link flags. But - ``emscripten_${EMSCRIPTEN_VERSION}`` is too vague by itself because the ABI + ``emscripten_${EMSCRIPTEN_VERSION}`` is too vague by itself because the platform also depends on various linker flags. - There are other communities which have similar problems and would also benefit - from a centralized standard for "Long Term Service" ABIs that the whole - ecosystem could use. However, the Emscripten team have so far not been willing - to provide a this standard since they consider dynamic linking an unusual use - case. Thus it is left for our ecosystem to solve the problem itself. The - platform tag should contains some indication of this. + There are other communities which have similar problems and would also + benefit from a centralized standard for "Long Term Service" Emscripten + platforms that the whole ecosystem could use. However, the Emscripten team + have so far not been willing to provide a this standard since they consider + dynamic linking an unusual use case. Thus it is left for our ecosystem to + solve the problem itself. The platform tag should contains some indication + of this. ``pyemscripten_${PYTHON_MAJOR_MINOR}_${PATCH}`` This would make it clearer which Python version is meant for use with each - ABI, but it leads to conceptual confusion since the platform has nothing to do - with Python. + platform, but it leads to conceptual confusion since the platform has + nothing to do with Python. ``pyodide_...`` For now the platform is defined by Pyodide so this connection would be made @@ -242,7 +247,7 @@ Alternative Options for the Platform Tag also more forwards compatible to a future where the definition of the platform moves upstream of Pyodide. -No ABI patch version +No patch version We hope never to need the patch version, but it's good to be prepared for unforseen problems. @@ -253,7 +258,8 @@ Fo Pyodide Users ---------------- We recommend the `Pyodide documentation on installing packages `__. We will make a -table showing which ``pyemscripten`` ABI each Pyodide version is compatible with. +table showing which ``pyemscripten`` platform version each Pyodide version is +compatible with. For Package Maintainers ----------------------- From 0c023d055be6c5943e56ea188545ed24d462c5c5 Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Tue, 17 Mar 2026 10:15:22 +0100 Subject: [PATCH 2/2] Add comment that application build implies shared library build --- peps/pep-0783.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/peps/pep-0783.rst b/peps/pep-0783.rst index 6abe44cc238..2086fcef41a 100644 --- a/peps/pep-0783.rst +++ b/peps/pep-0783.rst @@ -105,7 +105,7 @@ The PyEmscripten Platform The specification of the ``pyemscripten_${YEAR}_${PATCH}`` platform includes: * Which version of the Emscripten compiler is used -* What libraries are statically linked to the binary +* What libraries are statically linked to the application * What stack unwinding ABI is to be used * How the loader handles dependency lookup * That libraries cannot use ``-pthread`` @@ -122,6 +122,12 @@ plan to use each platform with. The PyEmscripten platforms are fully specified in `Pyodide's documentation on the PyEmscripten Platform `__. +To define the platform we need only indicate how the main application is +compiled and linked. This implies how to build a compatible shared library. +However, our documentation includes detailed instructions on how to build a +compatible shared library because we assume most people will be building shared +libraries. + The ``pyodide build`` tool knows how to create wheels that are compatible with the PyEmscripten platform. Unlike with manylinux wheels, there is no need for a Docker container to build ``pyemscripten`` wheels. All that is needed is a Linux