python · tiran · Aug 2, 2022 · Jul 29, 2022 · Jul 30, 2022 · Jul 30, 2022
diff --git a/Doc/includes/wasm-notavail.rst b/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.
diff --git a/Doc/library/asynchat.rst b/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()
 

@@ -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.

diff --git a/Doc/library/asyncore.rst b/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

@@ -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
 ------------

diff --git a/Doc/library/compileall.rst b/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
 ----------------

diff --git a/Doc/library/concurrent.futures.rst b/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
 ----------------

diff --git a/Doc/library/crypt.rst b/Doc/library/crypt.rst
@@ -38,6 +38,8 @@ this module.
 
 .. availability:: Unix, not VxWorks.
 
+.. include:: ../includes/wasm-notavail.rst
+
 Hashing Methods
 ---------------
 

@@ -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
 ----------------------

diff --git a/Doc/library/fcntl.rst b/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``

diff --git a/Doc/library/ftplib.rst b/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

diff --git a/Doc/library/getpass.rst b/Doc/library/getpass.rst
@@ -14,6 +14,7 @@
 
 The :mod:`getpass` module provides two functions:
 
+.. include:: ../includes/wasm-notavail.rst
 
 .. function:: getpass(prompt='Password: ', stream=None)
 

diff --git a/Doc/library/grp.rst b/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>``):

diff --git a/Doc/library/http.client.rst b/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:
 
 

diff --git a/Doc/library/http.server.rst b/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::

@@ -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:
 

diff --git a/Doc/library/intro.rst b/Doc/library/intro.rst
@@ -64,3 +64,50 @@ 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:
+
+Notes on WebAssembly platforms
+==============================
+
+The WebAssembly platforms ``wasm32-emscripten`` and ``wasm32-wasi`` provide a
+subset of POSIX APIs. WASM runtimes and browser are sandboxed and have
+limited access to host and rest of the world. Any standard library module,
+that uses processes, threading, networking (:mod:`socket`), 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 operations like blocking network I/O and :func:`~time.sleep`.
+
+The properties and behavior of Python on WebAssembly platforms depend on the
+`Emscripten`_ or `WASI`_-SDK version, WASM runtimes (browser, NodeJS, `wasmtime`_),
+and Python build time flags. WebAssembly, Emscripten, and WASI are evolving.
+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`` API.
+
+.. TODO: update with information from Tools/wasm/README.md
+
+* 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 dysfunctional.
+
+* Some functions are stubs that either don't do anything and always return some
+  hardcoded value.
+
+* Functions related to file descriptors, file permissions, file ownership, and
+  links are limited and don't support some operations.
+
+.. _Emscripten: https://emscripten.org/
+.. _WASI: https://wasi.dev/
+.. _wasmtime: https://wasmtime.dev/
+.. _Pyodide: https://pyodide.org/
+.. _PyScript: https://pyscript.net/
diff --git a/Doc/library/mmap.rst b/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`

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

diff --git a/Doc/library/nis.rst b/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:
 
 

diff --git a/Doc/library/nntplib.rst b/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::
-Original file line number
+Diff line change
@@ Expand Up / @@ -38,6 +38,8 @@ this module. @@
     .. availability:: Unix, not VxWorks.
+    .. include:: ../includes/wasm-notavail.rst
     Hashing Methods
     ---------------
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
Expand Up		@@ -14,6 +14,7 @@

		The :mod:`getpass` module provides two functions:
tiran marked this conversation as resolved. Show resolved Hide resolved

		.. include:: ../includes/wasm-notavail.rst

tiran marked this conversation as resolved. Show resolved Hide resolved
		.. function:: getpass(prompt='Password: ', stream=None)

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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:


Expand Down