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

Co-authored-by: Éric <merwok@netwok.org>
Co-authored-by: Michael Droettboom <mdboom@gmail.com>
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>

diff --git a/Doc/includes/wasm-notavail.rst b/Doc/includes/wasm-notavail.rst
new file mode 100644 (file)
index 0000000..e680e1f
--- /dev/null
+++ 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
index 777b7075b30de7f38c6db98e6f0bc5a049ab89f1..32e04ad6d195333dec5ec26773be43923ee43a3d 100644 (file)
--- 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()
 

diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
index 66c7c4c24a918391d1d258af5ea42bc96bcb52e0..b71006e32b2b8961df0a734696bf6b944c2b2056 100644 (file)
--- a/Doc/library/asyncio.rst
+++ b/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.

diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst
index 0084d754419d09e2641d705770a5d6c7a85a11d8..a3a4e90d05277e8a6516c7c92831b8bafa4490e6 100644 (file)
--- 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

diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst
index 983e412afafd990073b58f97a31b1a31c30b0ede..295a601a7bf197f3e14f2d22941a489db2e872e2 100644 (file)
--- a/Doc/library/cgi.rst
+++ b/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
 ------------

diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst
index de34664acb84ab7d815c8525f918fe748ac6f21b..7af46cf3200878dab9cff5a11dc226ed98f7f2c2 100644 (file)
--- 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
index db5971e4d60fc9dcdbc95a0dbb2144f2e1b04128..95c9e50991423f9026a13938d7701c75d4437809 100644 (file)
--- 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
index f585bbcbc18b8e33e61d7179b00b813ea4a2c57c..740084b40c5ac9660c393ac85b695b9f3ca85b0e 100644 (file)
--- 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
 ---------------
 

diff --git a/Doc/library/ensurepip.rst b/Doc/library/ensurepip.rst
index fa1b42cf48409402e1bf3031f224b1a666044bdf..34f45e20bae9d9cdc47e7c0b5752a66858ff2482 100644 (file)
--- a/Doc/library/ensurepip.rst
+++ b/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
 ----------------------

diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst
index 784e7071c2b3539795d68930c16caac9bbf2d6f8..997c7ea571fc03f39d0519e5b2bad1605ba0e5f0 100644 (file)
--- 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
index 2f94ac499285dbe2cc484090a22300c37e1b64e6..e5ba9eef4074b915c02d97b6581a39780be9e4a9 100644 (file)
--- 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
index 82b11919a3d2bf67eeb7ef40e80d51b93f96a4bb..d5bbe67fb30a62143fd6d8cb6805904fdad1eb7c 100644 (file)
--- a/Doc/library/getpass.rst
+++ b/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)
 

diff --git a/Doc/library/grp.rst b/Doc/library/grp.rst
index baa31752a2c750c73d7b0e8c79263fdd05a8c851..fabc22e4cf5979cb1ccc54ecc73250a46ce449b2 100644 (file)
--- 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
index e605f7b8b141721b71f17cd6cc050fe394e0e69f..8bb3187ef51d65cad8d38b6bef9c22126e8edacd 100644 (file)
--- 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
index 3bb7294ebb4a798d76569e2b4b223ec676dfbb27..48f952daae12f5a6605f082e1a7be85a4ff5db9c 100644 (file)
--- 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::

diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
index 65681ec093598c209e93d5d43799f5783eaffefc..0c10e7afee401fb2c199b049a470e246d0d8cb9d 100644 (file)
--- a/Doc/library/imaplib.rst
+++ b/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:
 

diff --git a/Doc/library/intro.rst b/Doc/library/intro.rst
index 120b174dc3b1e70244c1545d438d9340109c2a0b..1020924038e91fb2e1a1b47146a04c6f52359270 100644 (file)
--- a/Doc/library/intro.rst
+++ b/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/

diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst
index 36c15e9d1d92d1533cfd96788f9bd73e4c95cc11..c4f8781f2ac9936e79339c0ea332719932c2004b 100644 (file)
--- 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`

diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 3eb98791726de1598bd6bb2040e2be792363d23f..eaa946462a11c68b80cc64e54b32668bbf70300a 100644 (file)
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -8,6 +8,8 @@
 
 --------------
 
+.. include:: ../includes/wasm-notavail.rst
+
 Introduction
 ------------
 

diff --git a/Doc/library/nis.rst b/Doc/library/nis.rst
index fd3c3d9293d2472a683284db74cf965b9b0a8e47..3fa7916c37b6a56ca904d92340662fb905629c97 100644 (file)
--- 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
index 5aad44d929e87168848b97d04736016b250082a0..143e4e0c427f9a65ac4197ea9aca0885021680a4 100644 (file)
--- a/Doc/library/nntplib.rst
+++ b/Doc/library/nntplib.rst
@@ -38,6 +38,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::
 

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 9567dab81ff5ecc65385edf05b98635518b0c8a7..e5555c2355f12b6770424ae79040b30fa0cf6155 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -34,6 +34,14 @@ Notes on the availability of these functions:
 
 * On VxWorks, os.popen, os.fork, os.execv and os.spawn*p* are not supported.
 
+* On WebAssembly platforms ``wasm32-emscripten`` and ``wasm32-wasi``, large
+  parts of the :mod:`os` module are not available or behave differently. API
+  related to processes (e.g. :func:`~os.fork`, :func:`~os.execve`), signals
+  (e.g. :func:`~os.kill`, :func:`~os.wait`), and resources
+  (e.g. :func:`~os.nice`) are not available. Others like :func:`~os.getuid`
+  and :func:`~os.getpid` are emulated or stubs.
+
+
 .. note::
 
    All functions in this module raise :exc:`OSError` (or subclasses thereof) in
@@ -165,7 +173,7 @@ process and user.
 
    Return the filename corresponding to the controlling terminal of the process.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: environ
@@ -337,7 +345,7 @@ process and user.
    Return the effective group id of the current process.  This corresponds to the
    "set id" bit on the file being executed in the current process.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: geteuid()
@@ -346,7 +354,7 @@ process and user.
 
    Return the current process's effective user id.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: getgid()
@@ -357,6 +365,9 @@ process and user.
 
    .. availability:: Unix.
 
+      The function is a stub on Emscripten and WASI, see
+      :ref:`wasm-availability` for more information.
+
 
 .. function:: getgrouplist(user, group)
 
@@ -365,7 +376,7 @@ process and user.
    field from the password record for *user*, because that group ID will
    otherwise be potentially omitted.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -374,7 +385,7 @@ process and user.
 
    Return list of supplemental group ids associated with the current process.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. note::
 
@@ -402,7 +413,7 @@ process and user.
    falls back to ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the
    current real user id.
 
-   .. availability:: Unix, Windows.
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
 
 
 .. function:: getpgid(pid)
@@ -410,7 +421,7 @@ process and user.
    Return the process group id of the process with process id *pid*. If *pid* is 0,
    the process group id of the current process is returned.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 .. function:: getpgrp()
 
@@ -418,7 +429,7 @@ process and user.
 
    Return the id of the current process group.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: getpid()
@@ -427,6 +438,8 @@ process and user.
 
    Return the current process id.
 
+   The function is a stub on Emscripten and WASI, see
+   :ref:`wasm-availability` for more information.
 
 .. function:: getppid()
 
@@ -436,7 +449,7 @@ process and user.
    the id returned is the one of the init process (1), on Windows it is still
    the same id, which may be already reused by another process.
 
-   .. availability:: Unix, Windows.
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
 
    .. versionchanged:: 3.2
       Added support for Windows.
@@ -454,7 +467,7 @@ process and user.
    (respectively) the calling process, the process group of the calling process,
    or the real user ID of the calling process.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -465,7 +478,7 @@ process and user.
 
    Parameters for the :func:`getpriority` and :func:`setpriority` functions.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -475,7 +488,7 @@ process and user.
    Return a tuple (ruid, euid, suid) denoting the current process's
    real, effective, and saved user ids.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.2
 
@@ -485,7 +498,7 @@ process and user.
    Return a tuple (rgid, egid, sgid) denoting the current process's
    real, effective, and saved group ids.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.2
 
@@ -498,6 +511,9 @@ process and user.
 
    .. availability:: Unix.
 
+      The function is a stub on Emscripten and WASI, see
+      :ref:`wasm-availability` for more information.
+
 
 .. function:: initgroups(username, gid)
 
@@ -505,7 +521,7 @@ process and user.
    the groups of which the specified username is a member, plus the specified
    group id.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.2
 
@@ -539,21 +555,21 @@ process and user.
 
    Set the current process's effective group id.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: seteuid(euid)
 
    Set the current process's effective user id.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: setgid(gid)
 
    Set the current process' group id.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: setgroups(groups)
@@ -562,7 +578,7 @@ process and user.
    *groups*. *groups* must be a sequence, and each element must be an integer
    identifying a group. This operation is typically available only to the superuser.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. note:: On macOS, the length of *groups* may not exceed the
       system-defined maximum number of effective group ids, typically 16.
@@ -574,7 +590,7 @@ process and user.
    Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on
    which version is implemented (if any).  See the Unix manual for the semantics.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: setpgid(pid, pgrp)
@@ -583,7 +599,7 @@ process and user.
    process with id *pid* to the process group with id *pgrp*.  See the Unix manual
    for the semantics.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: setpriority(which, who, priority)
@@ -600,7 +616,7 @@ process and user.
    *priority* is a value in the range -20 to 19. The default priority is 0;
    lower priorities cause more favorable scheduling.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -609,14 +625,14 @@ process and user.
 
    Set the current process's real and effective group ids.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: setresgid(rgid, egid, sgid)
 
    Set the current process's real, effective, and saved group ids.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.2
 
@@ -625,7 +641,7 @@ process and user.
 
    Set the current process's real, effective, and saved user ids.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.2
 
@@ -634,21 +650,21 @@ process and user.
 
    Set the current process's real and effective user ids.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: getsid(pid)
 
    Call the system call :c:func:`getsid`.  See the Unix manual for the semantics.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: setsid()
 
    Call the system call :c:func:`setsid`.  See the Unix manual for the semantics.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: setuid(uid)
@@ -657,7 +673,7 @@ process and user.
 
    Set the current process's user id.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. placed in this section since it relates to errno.... a little weak
@@ -680,6 +696,9 @@ process and user.
 
    Set the current numeric umask and return the previous umask.
 
+   The function is a stub on Emscripten and WASI, see
+   :ref:`wasm-availability` for more information.
+
 
 .. function:: uname()
 
@@ -850,6 +869,8 @@ as internal buffering of data.
    2: stderr), the new file descriptor is :ref:`inheritable
    <fd_inheritance>`.
 
+   .. availability:: not WASI.
+
    .. versionchanged:: 3.4
       The new file descriptor is now non-inheritable.
 
@@ -861,6 +882,8 @@ as internal buffering of data.
    <fd_inheritance>` by default or non-inheritable if *inheritable*
    is ``False``.
 
+   .. availability:: not WASI.
+
    .. versionchanged:: 3.4
       Add the optional *inheritable* parameter.
 
@@ -878,6 +901,9 @@ as internal buffering of data.
 
    .. availability:: Unix.
 
+      The function is limited on Emscripten and WASI, see
+      :ref:`wasm-availability` for more information.
+
 
 .. function:: fchown(fd, uid, gid)
 
@@ -890,6 +916,9 @@ as internal buffering of data.
 
    .. availability:: Unix.
 
+      The function is limited on Emscripten and WASI, see
+      :ref:`wasm-availability` for more information.
+
 
 .. function:: fdatasync(fd)
 
@@ -978,6 +1007,9 @@ as internal buffering of data.
 
    .. availability:: Unix.
 
+      The function is limited on Emscripten and WASI, see
+      :ref:`wasm-availability` for more information.
+
    .. versionadded:: 3.5
 
 
@@ -1020,7 +1052,7 @@ as internal buffering of data.
    Make the calling process a session leader; make the tty the controlling tty,
    the stdin, the stdout, and the stderr of the calling process; close fd.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.11
 
@@ -1164,7 +1196,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    descriptors are :ref:`non-inheritable <fd_inheritance>`. For a (slightly) more
    portable approach, use the :mod:`pty` module.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionchanged:: 3.4
       The new file descriptors are now non-inheritable.
@@ -1190,7 +1222,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Return a pair of file descriptors ``(r, w)`` usable for reading and writing,
    respectively.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -1200,7 +1232,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Ensures that enough disk space is allocated for the file specified by *fd*
    starting from *offset* and continuing for *len* bytes.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten.
 
    .. versionadded:: 3.3
 
@@ -1427,7 +1459,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Cross-platform applications should not use *headers*, *trailers* and *flags*
    arguments.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. note::
 
@@ -1449,6 +1481,9 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
 
    .. availability:: Unix.
 
+      The function is limited on Emscripten and WASI, see
+      :ref:`wasm-availability` for more information.
+
    .. versionadded:: 3.5
 
 
@@ -1459,7 +1494,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Parameters to the :func:`sendfile` function, if the implementation supports
    them.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -1468,7 +1503,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Parameter to the :func:`sendfile` function, if the implementation supports
    it. The data won't be cached in the virtual memory and will be freed afterwards.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.11
 
@@ -1529,7 +1564,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Return the process group associated with the terminal given by *fd* (an open
    file descriptor as returned by :func:`os.open`).
 
-   .. availability:: Unix.
+   .. availability:: Unix, not WASI.
 
 
 .. function:: tcsetpgrp(fd, pg)
@@ -1537,7 +1572,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Set the process group associated with the terminal given by *fd* (an open file
    descriptor as returned by :func:`os.open`) to *pg*.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not WASI.
 
 
 .. function:: ttyname(fd)
@@ -1645,6 +1680,9 @@ Using the :mod:`subprocess` module, all file descriptors except standard
 streams are closed, and inheritable handles are only inherited if the
 *close_fds* parameter is ``False``.
 
+On WebAssembly platforms ``wasm32-emscripten`` and ``wasm32-wasi``, the file
+descriptor cannot be modified.
+
 .. function:: get_inheritable(fd)
 
    Get the "inheritable" flag of the specified file descriptor (a boolean).
@@ -1829,7 +1867,7 @@ features:
 
    .. audit-event:: os.chflags path,flags os.chflags
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
       The *follow_symlinks* argument.
@@ -1874,6 +1912,9 @@ features:
       read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
       constants or a corresponding integer value).  All other bits are ignored.
 
+      The function is limited on Emscripten and WASI, see
+      :ref:`wasm-availability` for more information.
+
    .. audit-event:: os.chmod path,mode,dir_fd os.chmod
 
    .. versionadded:: 3.3
@@ -1900,6 +1941,9 @@ features:
 
    .. availability:: Unix.
 
+      The function is limited on Emscripten and WASI, see
+      :ref:`wasm-availability` for more information.
+
    .. versionadded:: 3.3
       Added support for specifying *path* as an open file descriptor,
       and the *dir_fd* and *follow_symlinks* arguments.
@@ -1912,7 +1956,7 @@ features:
 
    Change the root directory of the current process to *path*.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -1952,7 +1996,7 @@ features:
 
    .. audit-event:: os.chflags path,flags os.lchflags
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -2169,7 +2213,7 @@ features:
    FIFO for reading, and the client opens it for writing.  Note that :func:`mkfifo`
    doesn't open the FIFO --- it just creates the rendezvous point.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
       The *dir_fd* argument.
@@ -2191,7 +2235,7 @@ features:
    This function can also support :ref:`paths relative to directory descriptors
    <dir_fd>`.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
       The *dir_fd* argument.
@@ -3059,6 +3103,9 @@ features:
 
    .. availability:: Unix, Windows.
 
+      The function is limited on Emscripten and WASI, see
+      :ref:`wasm-availability` for more information.
+
    .. versionchanged:: 3.2
       Added support for Windows 6.0 (Vista) symbolic links.
 
@@ -3670,7 +3717,7 @@ to be ignored.
 
    .. audit-event:: os.exec path,args,env os.execl
 
-   .. availability:: Unix, Windows.
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
       Added support for specifying *path* as an open file descriptor
@@ -3713,49 +3760,49 @@ written in Python, such as a mail server's external command delivery program.
    Exit code that means the command was used incorrectly, such as when the wrong
    number of arguments are given.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_DATAERR
 
    Exit code that means the input data was incorrect.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_NOINPUT
 
    Exit code that means an input file did not exist or was not readable.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_NOUSER
 
    Exit code that means a specified user did not exist.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_NOHOST
 
    Exit code that means a specified host did not exist.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_UNAVAILABLE
 
    Exit code that means that a required service is unavailable.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_SOFTWARE
 
    Exit code that means an internal software error was detected.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_OSERR
@@ -3763,7 +3810,7 @@ written in Python, such as a mail server's external command delivery program.
    Exit code that means an operating system error was detected, such as the
    inability to fork or create a pipe.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_OSFILE
@@ -3771,21 +3818,21 @@ written in Python, such as a mail server's external command delivery program.
    Exit code that means some system file did not exist, could not be opened, or had
    some other kind of error.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_CANTCREAT
 
    Exit code that means a user specified output file could not be created.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_IOERR
 
    Exit code that means that an error occurred while doing I/O on some file.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_TEMPFAIL
@@ -3794,7 +3841,7 @@ written in Python, such as a mail server's external command delivery program.
    that may not really be an error, such as a network connection that couldn't be
    made during a retryable operation.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_PROTOCOL
@@ -3802,7 +3849,7 @@ written in Python, such as a mail server's external command delivery program.
    Exit code that means that a protocol exchange was illegal, invalid, or not
    understood.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_NOPERM
@@ -3810,21 +3857,21 @@ written in Python, such as a mail server's external command delivery program.
    Exit code that means that there were insufficient permissions to perform the
    operation (but not intended for file system problems).
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_CONFIG
 
    Exit code that means that some kind of configuration error occurred.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: EX_NOTFOUND
 
    Exit code that means something like "an entry was not found".
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: fork()
@@ -3845,7 +3892,7 @@ written in Python, such as a mail server's external command delivery program.
 
       See :mod:`ssl` for applications that use the SSL module with fork().
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: forkpty()
@@ -3862,7 +3909,7 @@ written in Python, such as a mail server's external command delivery program.
       Calling ``forkpty()`` in a subinterpreter is no longer supported
       (:exc:`RuntimeError` is raised).
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: kill(pid, sig)
@@ -3886,6 +3933,8 @@ written in Python, such as a mail server's external command delivery program.
 
    .. audit-event:: os.kill pid,sig os.kill
 
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
+
    .. versionadded:: 3.2
       Windows support.
 
@@ -3900,14 +3949,14 @@ written in Python, such as a mail server's external command delivery program.
 
    .. audit-event:: os.killpg pgid,sig os.killpg
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: nice(increment)
 
    Add *increment* to the process's "niceness".  Return the new niceness.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: pidfd_open(pid, flags=0)
@@ -3937,7 +3986,7 @@ written in Python, such as a mail server's external command delivery program.
    Lock program segments into memory.  The value of *op* (defined in
    ``<sys/lock.h>``) determines which segments are locked.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: popen(cmd, mode='r', buffering=-1)
@@ -3969,6 +4018,8 @@ written in Python, such as a mail server's external command delivery program.
    documentation for more powerful ways to manage and communicate with
    subprocesses.
 
+   .. availability:: not Emscripten, not WASI.
+
    .. note::
       The :ref:`Python UTF-8 Mode <utf8-mode>` affects encodings used
       for *cmd* and pipe contents.
@@ -4062,7 +4113,7 @@ written in Python, such as a mail server's external command delivery program.
 
    .. versionadded:: 3.8
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 .. function:: posix_spawnp(path, argv, env, *, file_actions=None, \
                           setpgroup=None, resetids=False, setsid=False, setsigmask=(), \
@@ -4078,7 +4129,7 @@ written in Python, such as a mail server's external command delivery program.
 
    .. versionadded:: 3.8
 
-   .. availability:: POSIX
+   .. availability:: POSIX, not Emscripten, not WASI.
 
       See :func:`posix_spawn` documentation.
 
@@ -4111,7 +4162,7 @@ written in Python, such as a mail server's external command delivery program.
 
    There is no way to unregister a function.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.7
 
@@ -4180,7 +4231,7 @@ written in Python, such as a mail server's external command delivery program.
 
    .. audit-event:: os.spawn mode,path,args,env os.spawnl
 
-   .. availability:: Unix, Windows.
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
 
       :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
       and :func:`spawnvpe` are not available on Windows.  :func:`spawnle` and
@@ -4304,7 +4355,7 @@ written in Python, such as a mail server's external command delivery program.
 
    .. audit-event:: os.system command os.system
 
-   .. availability:: Unix, Windows.
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
 
 
 .. function:: times()
@@ -4345,7 +4396,7 @@ written in Python, such as a mail server's external command delivery program.
    :func:`waitstatus_to_exitcode` can be used to convert the exit status into an
    exit code.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. seealso::
 
@@ -4366,7 +4417,7 @@ written in Python, such as a mail server's external command delivery program.
    :attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no
    children in a waitable state.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -4377,7 +4428,7 @@ written in Python, such as a mail server's external command delivery program.
    These are the possible values for *idtype* in :func:`waitid`. They affect
    how *id* is interpreted.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -4397,7 +4448,7 @@ written in Python, such as a mail server's external command delivery program.
    Flags that can be used in *options* in :func:`waitid` that specify what
    child signal to wait for.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -4412,7 +4463,7 @@ written in Python, such as a mail server's external command delivery program.
    These are the possible values for :attr:`si_code` in the result returned by
    :func:`waitid`.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -4450,6 +4501,8 @@ written in Python, such as a mail server's external command delivery program.
    :func:`waitstatus_to_exitcode` can be used to convert the exit status into an
    exit code.
 
+   .. availability:: Unix, not Emscripten, not WASI.
+
    .. versionchanged:: 3.5
       If the system call is interrupted and the signal handler does not raise an
       exception, the function now retries the system call instead of raising an
@@ -4468,7 +4521,7 @@ written in Python, such as a mail server's external command delivery program.
    :func:`waitstatus_to_exitcode` can be used to convert the exit status into an
    exitcode.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: wait4(pid, options)
@@ -4482,7 +4535,7 @@ written in Python, such as a mail server's external command delivery program.
    :func:`waitstatus_to_exitcode` can be used to convert the exit status into an
    exitcode.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: waitstatus_to_exitcode(status)
@@ -4512,6 +4565,8 @@ written in Python, such as a mail server's external command delivery program.
       :func:`WIFEXITED`, :func:`WEXITSTATUS`, :func:`WIFSIGNALED`,
       :func:`WTERMSIG`, :func:`WIFSTOPPED`, :func:`WSTOPSIG` functions.
 
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
+
    .. versionadded:: 3.9
 
 
@@ -4520,7 +4575,7 @@ written in Python, such as a mail server's external command delivery program.
    The option for :func:`waitpid` to return immediately if no child process status
    is available immediately. The function returns ``(0, 0)`` in this case.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. data:: WCONTINUED
@@ -4528,7 +4583,7 @@ written in Python, such as a mail server's external command delivery program.
    This option causes child processes to be reported if they have been continued
    from a job control stop since their status was last reported.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
       Some Unix systems.
 
@@ -4538,7 +4593,7 @@ written in Python, such as a mail server's external command delivery program.
    This option causes child processes to be reported if they have been stopped but
    their current state has not been reported since they were stopped.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 The following functions take a process status code as returned by
@@ -4552,7 +4607,7 @@ used to determine the disposition of a process.
 
    This function should be employed only if :func:`WIFSIGNALED` is true.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: WIFCONTINUED(status)
@@ -4563,7 +4618,7 @@ used to determine the disposition of a process.
 
    See :data:`WCONTINUED` option.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: WIFSTOPPED(status)
@@ -4575,14 +4630,14 @@ used to determine the disposition of a process.
    done using :data:`WUNTRACED` option or when the process is being traced (see
    :manpage:`ptrace(2)`).
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 .. function:: WIFSIGNALED(status)
 
    Return ``True`` if the process was terminated by a signal, otherwise return
    ``False``.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: WIFEXITED(status)
@@ -4591,7 +4646,7 @@ used to determine the disposition of a process.
    by calling ``exit()`` or ``_exit()``, or by returning from ``main()``;
    otherwise return ``False``.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: WEXITSTATUS(status)
@@ -4600,7 +4655,7 @@ used to determine the disposition of a process.
 
    This function should be employed only if :func:`WIFEXITED` is true.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: WSTOPSIG(status)
@@ -4609,7 +4664,7 @@ used to determine the disposition of a process.
 
    This function should be employed only if :func:`WIFSTOPPED` is true.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 .. function:: WTERMSIG(status)
@@ -4618,7 +4673,7 @@ used to determine the disposition of a process.
 
    This function should be employed only if :func:`WIFSIGNALED` is true.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
 
 Interface to the scheduler

diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst
index 2f993f990de015c59e7559c7035e55cda396a4f2..e22a2e1455e7fcdff07eb6e4caf0c0db0beef2ac 100644 (file)
--- a/Doc/library/poplib.rst
+++ b/Doc/library/poplib.rst
@@ -28,6 +28,8 @@ quality of POP3 servers varies widely, and too many are quite poor. If your
 mailserver supports IMAP, you would be better off using the
 :class:`imaplib.IMAP4` class, as IMAP servers tend to be better implemented.
 
+.. include:: ../includes/wasm-notavail.rst
+
 The :mod:`poplib` module provides two classes:
 
 

diff --git a/Doc/library/pwd.rst b/Doc/library/pwd.rst
index 03ebb02e4e5136ffda973dae3d651af513c65927..98f3c45e29cbcbcd62cd27e0d8a11db4e5521bf5 100644 (file)
--- a/Doc/library/pwd.rst
+++ b/Doc/library/pwd.rst
@@ -10,6 +10,8 @@
 This module provides access to the Unix user account and password database.  It
 is available on all Unix versions.
 
+.. include:: ../includes/wasm-notavail.rst
+
 Password database entries are reported as a tuple-like object, whose attributes
 correspond to the members of the ``passwd`` structure (Attribute field below,
 see ``<pwd.h>``):

diff --git a/Doc/library/resource.rst b/Doc/library/resource.rst
index 7c9c5a0819b0a73ca1d9a21462dd92842ab5083f..e7bf45d7d569fa0f016d6597ed8051c75cfbe8bb 100644 (file)
--- a/Doc/library/resource.rst
+++ b/Doc/library/resource.rst
@@ -13,6 +13,8 @@
 This module provides basic mechanisms for measuring and controlling system
 resources utilized by a program.
 
+.. include:: ../includes/wasm-notavail.rst
+
 Symbolic constants are used to specify particular system resources and to
 request usage information about either the current process or its children.
 

diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index 1c3d10ef20935efc10a62db9f6e19ccb49e9dacb..a8df81f5bd1f0714dee09a6a2ddaac68738aedc4 100644 (file)
--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
@@ -22,6 +22,7 @@ it was last read.
    encouraged to use the :mod:`selectors` module instead, unless they want
    precise control over the OS-level primitives used.
 
+.. include:: ../includes/wasm-notavail.rst
 
 The module defines the following:
 

diff --git a/Doc/library/selectors.rst b/Doc/library/selectors.rst
index 6d864a836de075462b3aacce630d180ab2e84a55..0deb15cf4c5037692efa83d474abb1917bdf2cb9 100644 (file)
--- a/Doc/library/selectors.rst
+++ b/Doc/library/selectors.rst
@@ -38,6 +38,7 @@ users.
    :mod:`select`
       Low-level I/O multiplexing module.
 
+.. include:: ../includes/wasm-notavail.rst
 
 Classes
 -------

diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 72b8f03fc16df77cc7b19c51f68beaeb20c0a2da..2269f50cbaff99114b01a832170549d7608a2041 100644 (file)
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -24,6 +24,9 @@ explicitly reset (Python emulates the BSD style interface regardless of the
 underlying implementation), with the exception of the handler for
 :const:`SIGCHLD`, which follows the underlying implementation.
 
+On WebAssembly platforms ``wasm32-emscripten`` and ``wasm32-wasi``, signals
+are emulated and therefore behave differently. Several functions and signals
+are not available on these platforms.
 
 Execution of Python signal handlers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/Doc/library/smtpd.rst b/Doc/library/smtpd.rst
index 5a7e41c6d0983b48ea4e1d7e950bc0431c300137..ac0c9aeb23609100bf42e9995f5f958e31b75e6a 100644 (file)
--- a/Doc/library/smtpd.rst
+++ b/Doc/library/smtpd.rst
@@ -31,6 +31,7 @@ interaction behaviour with SMTP clients.
 The code supports :RFC:`5321`, plus the :rfc:`1870` SIZE and :rfc:`6531`
 SMTPUTF8 extensions.
 
+.. include:: ../includes/wasm-notavail.rst
 
 SMTPServer Objects
 ------------------

diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index aaab6b11d3bbe5f51bc138607576a92e9ac421c6..4e50ad1568ed0974a6889e0eaf2984c2a815fe45 100644 (file)
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -19,6 +19,7 @@ to send mail to any internet machine with an SMTP or ESMTP listener daemon.  For
 details of SMTP and ESMTP operation, consult :rfc:`821` (Simple Mail Transfer
 Protocol) and :rfc:`1869` (SMTP Service Extensions).
 
+.. include:: ../includes/wasm-notavail.rst
 
 .. class:: SMTP(host='', port=0, local_hostname=None[, timeout], source_address=None)
 

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 8eb254ce898e120a865072f4857f66e4b73dc7c5..b2bb8c7886747a1cfd61a160a2c3a765faa90211 100644 (file)
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -16,6 +16,9 @@ all modern Unix systems, Windows, MacOS, and probably additional platforms.
    Some behavior may be platform dependent, since calls are made to the operating
    system socket APIs.
 
+
+.. include:: ../includes/wasm-notavail.rst
+
 .. index:: object: socket
 
 The Python interface is a straightforward transliteration of the Unix system
@@ -918,6 +921,8 @@ The :mod:`socket` module also offers various network-related services:
 
    .. audit-event:: socket.gethostbyname hostname socket.gethostbyname
 
+   .. availability:: not WASI.
+
 
 .. function:: gethostbyname_ex(hostname)
 
@@ -932,6 +937,8 @@ The :mod:`socket` module also offers various network-related services:
 
    .. audit-event:: socket.gethostbyname hostname socket.gethostbyname_ex
 
+   .. availability:: not WASI.
+
 
 .. function:: gethostname()
 
@@ -943,6 +950,8 @@ The :mod:`socket` module also offers various network-related services:
    Note: :func:`gethostname` doesn't always return the fully qualified domain
    name; use :func:`getfqdn` for that.
 
+   .. availability:: not WASI.
+
 
 .. function:: gethostbyaddr(ip_address)
 
@@ -956,6 +965,8 @@ The :mod:`socket` module also offers various network-related services:
 
    .. audit-event:: socket.gethostbyaddr ip_address socket.gethostbyaddr
 
+   .. availability:: not WASI.
+
 
 .. function:: getnameinfo(sockaddr, flags)
 
@@ -971,6 +982,9 @@ The :mod:`socket` module also offers various network-related services:
 
    .. audit-event:: socket.getnameinfo sockaddr socket.getnameinfo
 
+   .. availability:: not WASI.
+
+
 .. function:: getprotobyname(protocolname)
 
    Translate an internet protocol name (for example, ``'icmp'``) to a constant
@@ -979,6 +993,8 @@ The :mod:`socket` module also offers various network-related services:
    (:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen
    automatically if the protocol is omitted or zero.
 
+   .. availability:: not WASI.
+
 
 .. function:: getservbyname(servicename[, protocolname])
 
@@ -988,6 +1004,8 @@ The :mod:`socket` module also offers various network-related services:
 
    .. audit-event:: socket.getservbyname servicename,protocolname socket.getservbyname
 
+   .. availability:: not WASI.
+
 
 .. function:: getservbyport(port[, protocolname])
 
@@ -997,6 +1015,8 @@ The :mod:`socket` module also offers various network-related services:
 
    .. audit-event:: socket.getservbyport port,protocolname socket.getservbyport
 
+   .. availability:: not WASI.
+
 
 .. function:: ntohl(x)
 
@@ -1130,7 +1150,7 @@ The :mod:`socket` module also offers various network-related services:
    buffer.  Raises :exc:`OverflowError` if *length* is outside the
    permissible range of values.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
       Most Unix platforms.
 
@@ -1153,7 +1173,7 @@ The :mod:`socket` module also offers various network-related services:
    amount of ancillary data that can be received, since additional
    data may be able to fit into the padding area.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Emscripten, not WASI.
 
       most Unix platforms.
 
@@ -1193,7 +1213,7 @@ The :mod:`socket` module also offers various network-related services:
    (index int, name string) tuples.
    :exc:`OSError` if the system call fails.
 
-   .. availability:: Unix, Windows.
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -1220,7 +1240,7 @@ The :mod:`socket` module also offers various network-related services:
    interface name.
    :exc:`OSError` if no interface with the given name exists.
 
-   .. availability:: Unix, Windows.
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -1237,7 +1257,7 @@ The :mod:`socket` module also offers various network-related services:
    interface index number.
    :exc:`OSError` if no interface with the given index exists.
 
-   .. availability:: Unix, Windows.
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
 
    .. versionadded:: 3.3
 
@@ -1254,7 +1274,7 @@ The :mod:`socket` module also offers various network-related services:
    The *fds* parameter is a sequence of file descriptors.
    Consult :meth:`sendmsg` for the documentation of these parameters.
 
-   .. availability:: Unix.
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
 
       Unix platforms supporting :meth:`~socket.sendmsg`
       and :const:`SCM_RIGHTS` mechanism.
@@ -1268,7 +1288,7 @@ The :mod:`socket` module also offers various network-related services:
    Return ``(msg, list(fds), flags, addr)``.
    Consult :meth:`recvmsg` for the documentation of these parameters.
 
-   .. availability:: Unix.
+   .. availability:: Unix, Windows, not Emscripten, not WASI.
 
       Unix platforms supporting :meth:`~socket.sendmsg`
       and :const:`SCM_RIGHTS` mechanism.
@@ -1319,6 +1339,9 @@ to sockets.
 
    .. audit-event:: socket.bind self,address socket.socket.bind
 
+   .. availability:: not WASI.
+
+
 .. method:: socket.close()
 
    Mark the socket closed.  The underlying system resource (e.g. a file
@@ -1363,6 +1386,8 @@ to sockets.
       signal, the signal handler doesn't raise an exception and the socket is
       blocking or has a timeout (see the :pep:`475` for the rationale).
 
+   .. availability:: not WASI.
+
 
 .. method:: socket.connect_ex(address)
 
@@ -1375,6 +1400,8 @@ to sockets.
 
    .. audit-event:: socket.connect self,address socket.socket.connect_ex
 
+   .. availability:: not WASI.
+
 .. method:: socket.detach()
 
    Put the socket object into closed state without actually closing the
@@ -1393,6 +1420,8 @@ to sockets.
    .. versionchanged:: 3.4
       The socket is now non-inheritable.
 
+   .. availability:: not WASI.
+
 
 .. method:: socket.fileno()
 
@@ -1438,6 +1467,8 @@ to sockets.
    contents of the buffer (see the optional built-in module :mod:`struct` for a way
    to decode C structures encoded as byte strings).
 
+   .. availability:: not WASI.
+
 
 .. method:: socket.getblocking()
 
@@ -1481,9 +1512,12 @@ to sockets.
    unaccepted connections that the system will allow before refusing new
    connections. If not specified, a default reasonable value is chosen.
 
+   .. availability:: not WASI.
+
    .. versionchanged:: 3.5
       The *backlog* parameter is now optional.
 
+
 .. method:: socket.makefile(mode='r', buffering=None, *, encoding=None, \
                             errors=None, newline=None)
 
@@ -1758,7 +1792,7 @@ to sockets.
       def send_fds(sock, msg, fds):
           return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])
 
-   .. availability:: Unix.
+   .. availability:: Unix, not WASI.
 
       Most Unix platforms.
 
@@ -1854,13 +1888,14 @@ to sockets.
    *optlen* argument is required. It's equivalent to call :c:func:`setsockopt` C
    function with ``optval=NULL`` and ``optlen=optlen``.
 
-
    .. versionchanged:: 3.5
       Writable :term:`bytes-like object` is now accepted.
 
    .. versionchanged:: 3.6
       setsockopt(level, optname, None, optlen: int) form added.
 
+   .. availability:: not WASI.
+
 
 .. method:: socket.shutdown(how)
 
@@ -1869,6 +1904,8 @@ to sockets.
    are disallowed.  If *how* is :const:`SHUT_RDWR`, further sends and receives are
    disallowed.
 
+   .. availability:: not WASI.
+
 
 .. method:: socket.share(process_id)
 

diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index b65a3e8fb2b975c9628279580a409b9d3eee8dc8..70d56a1dad94f208f2a3028a8cd3d67508ce17ce 100644 (file)
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -10,6 +10,8 @@
 
 The :mod:`socketserver` module simplifies the task of writing network servers.
 
+.. include:: ../includes/wasm-notavail.rst
+
 There are four basic concrete server classes:
 
 

diff --git a/Doc/library/spwd.rst b/Doc/library/spwd.rst
index 87e09167ada4275b60f23f230d604136d2b6a4ad..d1693ea67f0ceb7fad963dd25444aed2c954976a 100644 (file)
--- a/Doc/library/spwd.rst
+++ b/Doc/library/spwd.rst
@@ -15,6 +15,8 @@
 This module provides access to the Unix shadow password database. It is
 available on various Unix versions.
 
+.. include:: ../includes/wasm-notavail.rst
+
 You must have enough privileges to access the shadow password database (this
 usually means you have to be root).
 

diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index e6e9a08e0a7197f9489b90c56503fb578a5b3450..f5d5a7c4d282051174de12c7bb1c8bad8d169e53 100644 (file)
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -33,6 +33,7 @@ probably additional platforms, as long as OpenSSL is installed on that platform.
    may lead to a false sense of security, as the default settings of the
    ssl module are not necessarily appropriate for your application.
 
+.. include:: ../includes/wasm-notavail.rst
 
 This section documents the objects and functions in the ``ssl`` module; for more
 general information about TLS, SSL, and certificates, the reader is referred to

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index fae81f8ac28ff40885b45ad98982f8a6821c863d..43d6ffceee8fc85786f8385c4ca55752f65fb9b7 100644 (file)
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -25,6 +25,7 @@ modules and functions can be found in the following sections.
 
    :pep:`324` -- PEP proposing the subprocess module
 
+.. include:: ../includes/wasm-notavail.rst
 
 Using the :mod:`subprocess` Module
 ----------------------------------

diff --git a/Doc/library/syslog.rst b/Doc/library/syslog.rst
index ce51856ab7be1379568becbc185ddb28d843b2aa..766ff57cc66d69cc5a30336c4eaa5398f86b942b 100644 (file)
--- a/Doc/library/syslog.rst
+++ b/Doc/library/syslog.rst
@@ -15,6 +15,8 @@ This module wraps the system ``syslog`` family of routines.  A pure Python
 library that can speak to a syslog server is available in the
 :mod:`logging.handlers` module as :class:`SysLogHandler`.
 
+.. include:: ../includes/wasm-notavail.rst
+
 The module defines the following functions:
 
 

diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst
index 70b8c7d1511d09cced8b9f72f3f5feb612fa116a..5a993dc42a5ab2236d79bbe125f62e7dcf84536c 100644 (file)
--- a/Doc/library/telnetlib.rst
+++ b/Doc/library/telnetlib.rst
@@ -30,6 +30,7 @@ SE (Subnegotiation End), NOP (No Operation), DM (Data Mark), BRK (Break), IP
 (Interrupt process), AO (Abort output), AYT (Are You There), EC (Erase
 Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin).
 
+.. include:: ../includes/wasm-notavail.rst
 
 .. class:: Telnet(host=None, port=0[, timeout])
 

diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 8e69c2c404f63a5a677e84c6a21362414c500aed..a8851dd15052ef7896349579c748b1611a3c544f 100644 (file)
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -33,6 +33,7 @@ level :mod:`_thread` module.  See also the :mod:`queue` module.
    However, threading is still an appropriate model if you want to run
    multiple I/O-bound tasks simultaneously.
 
+.. include:: ../includes/wasm-notavail.rst
 
 This module defines the following functions:
 

diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index 542db1b5e2a39f808c78665a0ebe82f55ec6a8e1..59e1f2da828a833d95ab497a54dd5cc06e5f9202 100644 (file)
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -21,6 +21,7 @@ authentication, redirections, cookies and more.
     The `Requests package <https://requests.readthedocs.io/en/master/>`_
     is recommended for a higher-level HTTP client interface.
 
+.. include:: ../includes/wasm-notavail.rst
 
 The :mod:`urllib.request` module defines the following functions:
 

diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index 513a982c6ede6a4b7a79f3b422ff4946aa0e5438..06810612acba548a7e57a97b4b81cbb737da20aa 100644 (file)
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -29,6 +29,7 @@ See :pep:`405` for more information about Python virtual environments.
    `Python Packaging User Guide: Creating and using virtual environments
    <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`__
 
+.. include:: ../includes/wasm-notavail.rst
 
 Creating virtual environments
 -----------------------------

diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst
index 1dc59306164ecdc500469135f78863991c5c3316..734b6321e5a7e7e40a6bcd47bc2bf9b0ff79c132 100644 (file)
--- a/Doc/library/webbrowser.rst
+++ b/Doc/library/webbrowser.rst
@@ -41,6 +41,8 @@ naturally, mutually exclusive.  Usage example::
 
    python -m webbrowser -t "https://www.python.org"
 
+.. include:: ../includes/wasm-notavail.rst
+
 The following exception is defined:
 
 

diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst
index 0d9bfd51f1e496da0af35c699d3f533812196972..9f5ba46934b798ddd6f0923eda8100977f6268b9 100644 (file)
--- a/Doc/library/xmlrpc.client.rst
+++ b/Doc/library/xmlrpc.client.rst
@@ -32,6 +32,8 @@ between conformable Python objects and XML on the wire.
    For HTTPS URIs, :mod:`xmlrpc.client` now performs all the necessary
    certificate and hostname checks by default.
 
+.. include:: ../includes/wasm-notavail.rst
+
 .. class:: ServerProxy(uri, transport=None, encoding=None, verbose=False, \
                        allow_none=False, use_datetime=False, \
                        use_builtin_types=False, *, headers=(), context=None)

diff --git a/Doc/library/xmlrpc.server.rst b/Doc/library/xmlrpc.server.rst
index 7d561e2303f89848112981c7fc851b27320316d5..9778a859da1fbf70b7b1a08f211b1964fda85a1c 100644 (file)
--- a/Doc/library/xmlrpc.server.rst
+++ b/Doc/library/xmlrpc.server.rst
@@ -23,6 +23,7 @@ servers written in Python.  Servers can either be free standing, using
    constructed data.  If you need to parse untrusted or unauthenticated data see
    :ref:`xml-vulnerabilities`.
 
+.. include:: ../includes/wasm-notavail.rst
 
 .. class:: SimpleXMLRPCServer(addr, requestHandler=SimpleXMLRPCRequestHandler,\
                logRequests=True, allow_none=False, encoding=None,\

diff --git a/Doc/library/zoneinfo.rst b/Doc/library/zoneinfo.rst
index 1b2ba2af2ae6fbaf1ef364e95d040465d88b759e..2f1879dc056a881e7bc9e419eb29a83ed4a0a2d8 100644 (file)
--- a/Doc/library/zoneinfo.rst
+++ b/Doc/library/zoneinfo.rst
@@ -27,6 +27,7 @@ first-party `tzdata`_ package available on PyPI.
         First-party package maintained by the CPython core developers to supply
         time zone data via PyPI.
 
+.. include:: ../includes/wasm-notavail.rst
 
 Using ``ZoneInfo``
 ------------------

diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index 20c372e2495697ca6945b12a5d19fac40c61a9bb..da15abdf6372607e3e43a9dff58ab1a9167d90e7 100644 (file)
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -143,11 +143,11 @@ class Availability(Directive):
     known_platforms = frozenset({
         "AIX", "Android", "BSD", "DragonFlyBSD", "Emscripten", "FreeBSD",
         "Linux", "NetBSD", "OpenBSD", "POSIX", "Solaris", "Unix", "VxWorks",
-         "WASI", "Windows", "macOS",
-         # libc
-         "BSD libc", "glibc", "musl",
-         # POSIX platforms with pthreads
-         "pthreads",
+        "WASI", "Windows", "macOS",
+        # libc
+        "BSD libc", "glibc", "musl",
+        # POSIX platforms with pthreads
+        "pthreads",
     })
 
     def run(self):
@@ -159,9 +159,7 @@ class Availability(Directive):
         n, m = self.state.inline_text(self.arguments[0], self.lineno)
         pnode.extend(n + m)
         if self.content:
-            content = " " + " ".join(self.content)
-            n, m = self.state.inline_text(content, self.content_offset)
-            pnode.extend(n + m)
+            self.state.nested_parse(self.content, self.content_offset, pnode)
 
         self.parse_platforms()
 

diff --git a/Misc/NEWS.d/next/Documentation/2022-07-29-23-02-19.gh-issue-95451.-tgB93.rst b/Misc/NEWS.d/next/Documentation/2022-07-29-23-02-19.gh-issue-95451.-tgB93.rst
new file mode 100644 (file)
index 0000000..3a7b8a1
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-07-29-23-02-19.gh-issue-95451.-tgB93.rst
@@ -0,0 +1,3 @@
+Update library documentation with
+:ref:`availability information <wasm-availability>`
+on WebAssembly platforms ``wasm32-emscripten`` and ``wasm32-wasi``.