gh-84461: Add sys._emscripten_info, improve docs and build (gh-91781)

1 files changed, 54 insertions, 11 deletions

diff --git a/Tools/wasm/README.md b/Tools/wasm/README.md
index fa99703..9d3680a 100644
--- a/Tools/wasm/README.md
+++ b/Tools/wasm/README.md
@@ -4,11 +4,17 @@
 
 This directory contains configuration and helpers to facilitate cross
 compilation of CPython to WebAssembly (WASM). For now we support
-*wasm32-emscripten* builds for modern browser and for *Node.js*. It's not
-possible to build for *wasm32-wasi* out-of-the-box yet.
+*wasm32-emscripten* builds for modern browser and for *Node.js*. WASI
+(*wasm32-wasi*) is work-in-progress
 
 ## wasm32-emscripten build
 
+For now the build system has two target flavors. The ``Emscripten/browser``
+target (``--with-emscripten-target=browser``) is optimized for browsers.
+It comes with a reduced and preloaded stdlib without tests and threading
+support. The ``Emscripten/node`` target has threading enabled and can
+access the file system directly.
+
 Cross compiling to the wasm32-emscripten platform needs the
 [Emscripten](https://emscripten.org/) SDK and a build Python interpreter.
 Emscripten 3.1.8 or newer are recommended. All commands below are relative
@@ -76,7 +82,7 @@ and header files with debug builds.
 
 ### Cross compile to wasm32-emscripten for node
 
-```
+```shell
 mkdir -p builddir/emscripten-node
 pushd builddir/emscripten-node
 
@@ -91,7 +97,7 @@ emmake make -j$(nproc)
 popd
 ```
 
-```
+```shell
 node --experimental-wasm-threads --experimental-wasm-bulk-memory builddir/emscripten-node/python.js
 ```
 
@@ -150,9 +156,9 @@ functions.
 - Most stdlib modules with a dependency on external libraries are missing,
   e.g. ``ctypes``, ``readline``, ``sqlite3``, ``ssl``, and more.
 - Shared extension modules are not implemented yet. All extension modules
-  are statically linked into the main binary.
-  The experimental configure option ``--enable-wasm-dynamic-linking`` enables
-  dynamic extensions.
+  are statically linked into the main binary. The experimental configure
+  option ``--enable-wasm-dynamic-linking`` enables dynamic extensions
+  supports. It's currently known to crash in combination with threading.
 - glibc extensions for date and time formatting are not available.
 - ``locales`` module is affected by musl libc issues,
   [bpo-46390](https://bugs.python.org/issue46390).
@@ -167,8 +173,10 @@ functions.
   distutils, multiprocessing, dbm, tests and similar modules
   are not shipped. All other modules are bundled as pre-compiled
   ``pyc`` files.
-- Threading is not supported.
+- Threading is disabled.
 - In-memory file system (MEMFS) is not persistent and limited.
+- Test modules are disabled by default. Use ``--enable-test-modules`` build
+  test modules like ``_testcapi``.
 
 ## wasm32-emscripten in node
 
@@ -205,11 +213,17 @@ AddType application/wasm wasm
 </IfModule>
 ```
 
+# WASI (wasm32-wasi)
+
+WASI builds require [WASI SDK](https://github.com/WebAssembly/wasi-sdk) and
+currently [wasix](https://github.com/singlestore-labs/wasix) for POSIX
+compatibility stubs.
+
 # Detect WebAssembly builds
 
 ## Python code
 
-```# python
+```python
 import os, sys
 
 if sys.platform == "emscripten":
@@ -222,7 +236,36 @@ if os.name == "posix":
     # Windows does not provide os.uname().
     machine = os.uname().machine
     if machine.startswith("wasm"):
-        # WebAssembly (wasm32 or wasm64)
+        # WebAssembly (wasm32, wasm64 in the future)
+```
+
+```python
+>>> import os, sys
+>>> os.uname()
+posix.uname_result(sysname='Emscripten', nodename='emscripten', release='1.0', version='#1', machine='wasm32')
+>>> os.name
+'posix'
+>>> sys.platform
+'emscripten'
+>>> sys._emscripten_info
+sys._emscripten_info(
+    emscripten_version=(3, 1, 8),
+    runtime='Mozilla/5.0 (X11; Fedora; Linux x86_64; rv:99.0) Gecko/20100101 Firefox/99.0',
+    pthreads=False,
+    shared_memory=False
+)
+>>> sys._emscripten_info
+sys._emscripten_info(emscripten_version=(3, 1, 8), runtime='Node.js v14.18.2', pthreads=True, shared_memory=True)
+```
+
+```python
+>>> import os, sys
+>>> os.uname()
+posix.uname_result(sysname='wasi', nodename='(none)', release='0.0.0', version='0.0.0', machine='wasm32')
+>>> os.name
+'posix'
+>>> sys.platform
+'wasi'
 ```
 
 ## C code
@@ -231,7 +274,7 @@ Emscripten SDK and WASI SDK define several built-in macros. You can dump a
 full list of built-ins with ``emcc -dM -E - < /dev/null`` and
 ``/path/to/wasi-sdk/bin/clang -dM -E - < /dev/null``.
 
-```# C
+```C
 #ifdef __EMSCRIPTEN__
     // Python on Emscripten
 #endif