gh-95451: Update docs for wasm32-emscripten and -wasi platforms (GH-95452)

Co-authored-by: Éric <[email protected]>
Co-authored-by: Michael Droettboom <[email protected]>
Co-authored-by: Ezio Melotti <[email protected]>
Co-authored-by: CAM Gerlach <[email protected]>
(cherry picked from commit e3b6ff1)

Co-authored-by: Christian Heimes <[email protected]>

Author: miss-islington

Doc/includes/wasm-notavail.rst

@@ -0,0 +1,7 @@
+.. include for modules that don't work on WASM
+
+.. availability:: not Emscripten, not WASI.
+
+   This module does not work or is not available on WebAssembly platforms
+   ``wasm32-emscripten`` and ``wasm32-wasi``. See
+   :ref:`wasm-availability` for more information.

Doc/library/asynchat.rst

@@ -34,6 +34,7 @@ Typically an :class:`asyncore.dispatcher` server channel generates new
 :class:`asynchat.async_chat` channel objects as it receives incoming
 connection requests.
 
+.. include:: ../includes/wasm-notavail.rst
 
 .. class:: async_chat()
 

Doc/library/asyncio.rst

@@ -56,6 +56,7 @@ Additionally, there are **low-level** APIs for
 * :ref:`bridge <asyncio-futures>` callback-based libraries and code
   with async/await syntax.
 
+.. include:: ../includes/wasm-notavail.rst
 
 .. We use the "rubric" directive here to avoid creating
    the "Reference" subsection in the TOC.

Doc/library/asyncore.rst

@@ -28,6 +28,8 @@
 This module provides the basic infrastructure for writing asynchronous  socket
 service clients and servers.
 
+.. include:: ../includes/wasm-notavail.rst
+
 There are only two ways to have a program on a single processor do  "more than
 one thing at a time." Multi-threaded programming is the  simplest and most
 popular way to do it, but there is another very different technique, that lets

Doc/library/cgi.rst

@@ -37,6 +37,7 @@ size of a POST request. POST requests larger than this size will result in a
 :exc:`ValueError` being raised during parsing. The default value of this
 variable is ``0``, meaning the request size is unlimited.
 
+.. include:: ../includes/wasm-notavail.rst
 
 Introduction
 ------------

Doc/library/compileall.rst

@@ -14,6 +14,7 @@ This module can be used to create the cached byte-code files at library
 installation time, which makes them available for use even by users who don't
 have write permission to the library directories.
 
+.. include:: ../includes/wasm-notavail.rst
 
 Command-line use
 ----------------

Doc/library/concurrent.futures.rst

@@ -19,6 +19,7 @@ The asynchronous execution can be performed with threads, using
 :class:`ProcessPoolExecutor`.  Both implement the same interface, which is
 defined by the abstract :class:`Executor` class.
 
+.. include:: ../includes/wasm-notavail.rst
 
 Executor Objects
 ----------------

Doc/library/crypt.rst

@@ -38,6 +38,8 @@ this module.
 
 .. availability:: Unix, not VxWorks.
 
+.. include:: ../includes/wasm-notavail.rst
+
 Hashing Methods
 ---------------
 

Doc/library/ensurepip.rst

@@ -36,6 +36,7 @@ when creating a virtual environment) or after explicitly uninstalling
    :pep:`453`: Explicit bootstrapping of pip in Python installations
       The original rationale and specification for this module.
 
+.. include:: ../includes/wasm-notavail.rst
 
 Command line interface
 ----------------------

Doc/library/fcntl.rst

@@ -18,6 +18,8 @@ interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines.  For a
 complete description of these calls, see :manpage:`fcntl(2)` and
 :manpage:`ioctl(2)` Unix manual pages.
 
+.. include:: ../includes/wasm-notavail.rst
+
 All functions in this module take a file descriptor *fd* as their first
 argument.  This can be an integer file descriptor, such as returned by
 ``sys.stdin.fileno()``, or an :class:`io.IOBase` object, such as ``sys.stdin``

Doc/library/ftplib.rst

@@ -21,6 +21,8 @@ as mirroring other FTP servers.  It is also used by the module
 
 The default encoding is UTF-8, following :rfc:`2640`.
 
+.. include:: ../includes/wasm-notavail.rst
+
 Here's a sample session using the :mod:`ftplib` module::
 
    >>> from ftplib import FTP

Doc/library/getpass.rst

@@ -12,8 +12,9 @@
 
 --------------
 
-The :mod:`getpass` module provides two functions:
+.. include:: ../includes/wasm-notavail.rst
 
+The :mod:`getpass` module provides two functions:
 
 .. function:: getpass(prompt='Password: ', stream=None)
 

Doc/library/grp.rst

@@ -10,6 +10,8 @@
 This module provides access to the Unix group database. It is available on all
 Unix versions.
 
+.. include:: ../includes/wasm-notavail.rst
+
 Group database entries are reported as a tuple-like object, whose attributes
 correspond to the members of the ``group`` structure (Attribute field below, see
 ``<grp.h>``):

Doc/library/http.client.rst

@@ -28,6 +28,8 @@ HTTPS protocols.  It is normally not used directly --- the module
    HTTPS support is only available if Python was compiled with SSL support
    (through the :mod:`ssl` module).
 
+.. include:: ../includes/wasm-notavail.rst
+
 The module provides the following classes:
 
 

Doc/library/http.server.rst

@@ -22,6 +22,8 @@ This module defines classes for implementing HTTP servers.
     :mod:`http.server` is not recommended for production. It only implements
     :ref:`basic security checks <http.server-security>`.
 
+.. include:: ../includes/wasm-notavail.rst
+
 One class, :class:`HTTPServer`, is a :class:`socketserver.TCPServer` subclass.
 It creates and listens at the HTTP socket, dispatching the requests to a
 handler.  Code to create and run the server looks like this::

Doc/library/imaplib.rst

@@ -26,6 +26,8 @@ implement a large subset of the IMAP4rev1 client protocol as defined in
 :rfc:`2060`. It is backward compatible with IMAP4 (:rfc:`1730`) servers, but
 note that the ``STATUS`` command is not supported in IMAP4.
 
+.. include:: ../includes/wasm-notavail.rst
+
 Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
 base class:
 

Doc/library/intro.rst

@@ -64,3 +64,58 @@ Notes on availability
   libc version, then both conditions must hold. For example a feature with note
   *Availability: Linux >= 3.17 with glibc >= 2.27* requires both Linux 3.17 or
   newer and glibc 2.27 or newer.
+
+.. _wasm-availability:
+
+WebAssembly platforms
+---------------------
+
+The `WebAssembly`_ platforms ``wasm32-emscripten`` (`Emscripten`_) and
+``wasm32-wasi`` (`WASI`_) provide a subset of POSIX APIs. WebAssembly runtimes
+and browsers are sandboxed and have limited access to the host and external
+resources. Any Python standard library module that uses processes, threading,
+networking, signals, or other forms of inter-process communication (IPC), is
+either not available or may not work as on other Unix-like systems. File I/O,
+file system, and Unix permission-related functions are restricted, too.
+Emscripten does not permit blocking I/O. Other blocking operations like
+:func:`~time.sleep` block the browser event loop.
+
+The properties and behavior of Python on WebAssembly platforms depend on the
+`Emscripten`_-SDK or `WASI`_-SDK version, WASM runtimes (browser, NodeJS,
+`wasmtime`_), and Python build time flags. WebAssembly, Emscripten, and WASI
+are evolving standards; some features like networking may be
+supported in the future.
+
+For Python in the browser, users should consider `Pyodide`_ or `PyScript`_.
+PyScript is built on top of Pyodide, which itself is built on top of
+CPython and Emscripten. Pyodide provides access to browsers' JavaScript and
+DOM APIs as well as limited networking capabilities with JavaScript's
+``XMLHttpRequest`` and ``Fetch`` APIs.
+
+* Process-related APIs are not available or always fail with an error. That
+  includes APIs that spawn new processes (:func:`~os.fork`,
+  :func:`~os.execve`), wait for processes (:func:`~os.waitpid`), send signals
+  (:func:`~os.kill`), or otherwise interact with processes. The
+  :mod:`subprocess` is importable but does not work.
+
+* The :mod:`socket` module is available, but is limited and behaves
+  differently from other platforms. On Emscripten, sockets are always
+  non-blocking and require additional JavaScript code and helpers on the
+  server to proxy TCP through WebSockets; see `Emscripten Networking`_
+  for more information. WASI snapshot preview 1 only permits sockets from an
+  existing file descriptor.
+
+* Some functions are stubs that either don't do anything and always return
+  hardcoded values.
+
+* Functions related to file descriptors, file permissions, file ownership, and
+  links are limited and don't support some operations. For example, WASI does
+  not permit symlinks with absolute file names.
+
+.. _WebAssembly: https://webassembly.org/
+.. _Emscripten: https://emscripten.org/
+.. _Emscripten Networking: https://emscripten.org/docs/porting/networking.html>
+.. _WASI: https://wasi.dev/
+.. _wasmtime: https://wasmtime.dev/
+.. _Pyodide: https://pyodide.org/
+.. _PyScript: https://pyscript.net/

Doc/library/mmap.rst

@@ -6,6 +6,8 @@
 
 --------------
 
+.. include:: ../includes/wasm-notavail.rst
+
 Memory-mapped file objects behave like both :class:`bytearray` and like
 :term:`file objects <file object>`.  You can use mmap objects in most places
 where :class:`bytearray` are expected; for example, you can use the :mod:`re`

Doc/library/multiprocessing.rst

@@ -8,6 +8,8 @@
 
 --------------
 
+.. include:: ../includes/wasm-notavail.rst
+
 Introduction
 ------------
 

Doc/library/nis.rst

@@ -21,6 +21,8 @@ central administration of several hosts.
 
 Because NIS exists only on Unix systems, this module is only available for Unix.
 
+.. include:: ../includes/wasm-notavail.rst
+
 The :mod:`nis` module defines the following functions:
 
 

Doc/library/nntplib.rst

@@ -21,6 +21,8 @@ the Network News Transfer Protocol.  It can be used to implement a news reader
 or poster, or automated news processors.  It is compatible with :rfc:`3977`
 as well as the older :rfc:`977` and :rfc:`2980`.
 
+.. include:: ../includes/wasm-notavail.rst
+
 Here are two small examples of how it can be used.  To list some statistics
 about a newsgroup and print the subjects of the last 10 articles::