[Python-checkins] gh-95451: Update docs for wasm32-emscripten and -wasi platforms (GH-95452)
miss-islington
webhook-mailer at python.org
Tue Aug 2 15:13:16 EDT 2022
https://github.com/python/cpython/commit/72cad6cfe5e8d0b424bdd224feee6a22631ec3e6
commit: 72cad6cfe5e8d0b424bdd224feee6a22631ec3e6
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-08-02T12:13:07-07:00
summary:
gh-95451: Update docs for wasm32-emscripten and -wasi platforms (GH-95452)
Co-authored-by: Éric <merwok at netwok.org>
Co-authored-by: Michael Droettboom <mdboom at gmail.com>
Co-authored-by: Ezio Melotti <ezio.melotti at gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach at Gerlach.CAM>
(cherry picked from commit e3b6ff19aaa318a813130ba9ad2ab0a332f27feb)
Co-authored-by: Christian Heimes <christian at python.org>
files:
A Doc/includes/wasm-notavail.rst
A Misc/NEWS.d/next/Documentation/2022-07-29-23-02-19.gh-issue-95451.-tgB93.rst
M Doc/library/asynchat.rst
M Doc/library/asyncio.rst
M Doc/library/asyncore.rst
M Doc/library/cgi.rst
M Doc/library/compileall.rst
M Doc/library/concurrent.futures.rst
M Doc/library/crypt.rst
M Doc/library/ensurepip.rst
M Doc/library/fcntl.rst
M Doc/library/ftplib.rst
M Doc/library/getpass.rst
M Doc/library/grp.rst
M Doc/library/http.client.rst
M Doc/library/http.server.rst
M Doc/library/imaplib.rst
M Doc/library/intro.rst
M Doc/library/mmap.rst
M Doc/library/multiprocessing.rst
M Doc/library/nis.rst
M Doc/library/nntplib.rst
M Doc/library/os.rst
M Doc/library/poplib.rst
M Doc/library/pwd.rst
M Doc/library/resource.rst
M Doc/library/select.rst
M Doc/library/selectors.rst
M Doc/library/signal.rst
M Doc/library/smtpd.rst
M Doc/library/smtplib.rst
M Doc/library/socket.rst
M Doc/library/socketserver.rst
M Doc/library/spwd.rst
M Doc/library/ssl.rst
M Doc/library/subprocess.rst
M Doc/library/syslog.rst
M Doc/library/telnetlib.rst
M Doc/library/threading.rst
M Doc/library/urllib.request.rst
M Doc/library/venv.rst
M Doc/library/webbrowser.rst
M Doc/library/xmlrpc.client.rst
M Doc/library/xmlrpc.server.rst
M Doc/library/zoneinfo.rst
M Doc/tools/extensions/pyspecific.py
diff --git a/Doc/includes/wasm-notavail.rst b/Doc/includes/wasm-notavail.rst
new file mode 100644
index 00000000000..e680e1f9b43
--- /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 777b7075b30..32e04ad6d19 100644
--- 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 66c7c4c24a9..b71006e32b2 100644
--- 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 0084d754419..a3a4e90d052 100644
--- 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 983e412afaf..295a601a7bf 100644
--- 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 de34664acb8..7af46cf3200 100644
--- 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 db5971e4d60..95c9e509914 100644
--- 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 f585bbcbc18..740084b40c5 100644
--- 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 fa1b42cf484..34f45e20bae 100644
--- 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 1ecd552fbd0..c5a7ba0150e 100644
--- 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 2f94ac49928..e5ba9eef407 100644
--- 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 82b11919a3d..d5bbe67fb30 100644
--- 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 baa31752a2c..fabc22e4cf5 100644
--- 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 e605f7b8b14..8bb3187ef51 100644
--- 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 3bb7294ebb4..48f952daae1 100644
--- 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 65681ec0935..0c10e7afee4 100644
--- 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 120b174dc3b..1020924038e 100644
--- 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 36c15e9d1d9..c4f8781f2ac 100644
--- 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 3eb98791726..eaa946462a1 100644
--- 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 fd3c3d9293d..3fa7916c37b 100644
--- 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 2a996e451bf..a36c8a5dcce 100644
--- 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::
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index de6f27c5d32..8fccef2c2cf 100644
--- 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()
@@ -836,6 +855,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.
@@ -847,6 +868,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.
@@ -864,6 +887,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)
@@ -876,6 +902,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)
@@ -964,6 +993,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
@@ -1006,7 +1038,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
@@ -1150,7 +1182,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.
@@ -1176,7 +1208,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
@@ -1186,7 +1218,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
@@ -1413,7 +1445,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::
@@ -1435,6 +1467,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
@@ -1445,7 +1480,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
@@ -1454,7 +1489,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
@@ -1515,7 +1550,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)
@@ -1523,7 +1558,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)
@@ -1631,6 +1666,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).
@@ -1815,7 +1853,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.
@@ -1860,6 +1898,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
@@ -1886,6 +1927,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.
@@ -1898,7 +1942,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`.
@@ -1938,7 +1982,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`.
@@ -2155,7 +2199,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.
@@ -2177,7 +2221,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.
@@ -3045,6 +3089,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.
@@ -3656,7 +3703,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
@@ -3699,49 +3746,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
@@ -3749,7 +3796,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
@@ -3757,21 +3804,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
@@ -3780,7 +3827,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
@@ -3788,7 +3835,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
@@ -3796,21 +3843,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()
@@ -3831,7 +3878,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()
@@ -3848,7 +3895,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)
@@ -3872,6 +3919,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.
@@ -3886,14 +3935,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)
@@ -3914,7 +3963,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)
@@ -3946,6 +3995,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.
@@ -4039,7 +4090,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=(), \
@@ -4055,7 +4106,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.
@@ -4088,7 +4139,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
@@ -4157,7 +4208,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
@@ -4281,7 +4332,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()
@@ -4322,7 +4373,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::
@@ -4343,7 +4394,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
@@ -4354,7 +4405,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
@@ -4374,7 +4425,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
@@ -4389,7 +4440,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
@@ -4427,6 +4478,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
@@ -4445,7 +4498,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)
@@ -4459,7 +4512,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)
@@ -4489,6 +4542,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
@@ -4497,7 +4552,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
@@ -4505,7 +4560,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.
@@ -4515,7 +4570,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
@@ -4529,7 +4584,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)
@@ -4540,7 +4595,7 @@ used to determine the disposition of a process.
See :data:`WCONTINUED` option.
- .. availability:: Unix.
+ .. availability:: Unix, not Emscripten, not WASI.
.. function:: WIFSTOPPED(status)
@@ -4552,14 +4607,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)
@@ -4568,7 +4623,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)
@@ -4577,7 +4632,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)
@@ -4586,7 +4641,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)
@@ -4595,7 +4650,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 2f993f990de..e22a2e1455e 100644
--- 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 03ebb02e4e5..98f3c45e29c 100644
--- 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 7c9c5a0819b..e7bf45d7d56 100644
--- 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 1c3d10ef209..a8df81f5bd1 100644
--- 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 6d864a836de..0deb15cf4c5 100644
--- 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 72b8f03fc16..2269f50cbaf 100644
--- 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 5a7e41c6d09..ac0c9aeb236 100644
--- 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 aaab6b11d3b..4e50ad1568e 100644
--- 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 f35df364a34..c4bf3dcf32a 100644
--- 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
@@ -871,6 +874,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)
@@ -885,6 +890,8 @@ The :mod:`socket` module also offers various network-related services:
.. audit-event:: socket.gethostbyname hostname socket.gethostbyname_ex
+ .. availability:: not WASI.
+
.. function:: gethostname()
@@ -896,6 +903,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)
@@ -909,6 +918,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)
@@ -924,6 +935,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
@@ -932,6 +946,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])
@@ -941,6 +957,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])
@@ -950,6 +968,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)
@@ -1083,7 +1103,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.
@@ -1106,7 +1126,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.
@@ -1146,7 +1166,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
@@ -1173,7 +1193,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
@@ -1190,7 +1210,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
@@ -1207,7 +1227,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.
@@ -1221,7 +1241,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.
@@ -1272,6 +1292,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
@@ -1316,6 +1339,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)
@@ -1328,6 +1353,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
@@ -1346,6 +1373,8 @@ to sockets.
.. versionchanged:: 3.4
The socket is now non-inheritable.
+ .. availability:: not WASI.
+
.. method:: socket.fileno()
@@ -1391,6 +1420,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()
@@ -1434,9 +1465,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)
@@ -1711,7 +1745,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.
@@ -1807,13 +1841,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)
@@ -1822,6 +1857,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 b65a3e8fb2b..70d56a1dad9 100644
--- 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 87e09167ada..d1693ea67f0 100644
--- 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 dd6d243734a..a0aa45e9008 100644
--- 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 fae81f8ac28..43d6ffceee8 100644
--- 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 d264a3340c9..16093d5aac7 100644
--- 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 70b8c7d1511..5a993dc42a5 100644
--- 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 cc266fa323b..9511eaebf15 100644
--- 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 542db1b5e2a..59e1f2da828 100644
--- 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 b40bd4102c2..3fa1046ae97 100644
--- 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 1dc59306164..734b6321e5a 100644
--- 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 0d9bfd51f1e..9f5ba46934b 100644
--- 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 7d561e2303f..9778a859da1 100644
--- 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 1b2ba2af2ae..2f1879dc056 100644
--- 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 a795e05b8b9..f326e77b263 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -144,11 +144,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):
@@ -160,9 +160,7 @@ def run(self):
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
index 00000000000..3a7b8a122b7
--- /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``.
More information about the Python-checkins
mailing list