PEP 783: Clarify that PyEmscripten platform is independent of Python (#4863)

And of Python version. Also adjust wording: prefer "Platform" over "ABI"
in most places.

Co-authored-by: Maciej Olko <maciej.olko@gmail.com>

Author: hoodmane

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,54 @@ 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_<abi>`` 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 application
 * 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
-<https://pyodide.org/en/stable/development/abi.html>`__ 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_<abi>`` 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 <https://pyodide.org/en/stable/development/abi.html>`__.
 
-It is possible to validate a wheel by installing and importing it into the
+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
+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 +156,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 +172,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 +229,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 contain 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 +253,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 +264,8 @@ Fo Pyodide Users
 ----------------
 We recommend the `Pyodide documentation on installing packages
 <https://pyodide.org/en/stable/usage/loading-packages.html>`__. 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
 -----------------------