diff options
| author | Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> | 2022-08-02 19:13:07 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-08-02 19:13:07 (GMT) |
| commit | 72cad6cfe5e8d0b424bdd224feee6a22631ec3e6 (patch) | |
| tree | 2254c6bea85fbfc25db23b73174a62b5ecd6ee59 | |
| parent | 698b52c8791122e1e2a0aaa8708544c1a7cda68f (diff) | |
| download | cpython-72cad6cfe5e8d0b424bdd224feee6a22631ec3e6.zip cpython-72cad6cfe5e8d0b424bdd224feee6a22631ec3e6.tar.gz cpython-72cad6cfe5e8d0b424bdd224feee6a22631ec3e6.tar.bz2 | |
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>
(cherry picked from commit e3b6ff19aaa318a813130ba9ad2ab0a332f27feb)
Co-authored-by: Christian Heimes <christian@python.org>
46 files changed, 322 insertions, 105 deletions
diff --git a/Doc/includes/wasm-notavail.rst b/Doc/includes/wasm-notavail.rst new file mode 100644 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 777b707..32e04ad 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 66c7c4c..b71006e 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 0084d75..a3a4e90 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 983e412..295a601 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 de34664..7af46cf 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 db5971e..95c9e50 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 f585bbc..740084b 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 fa1b42c..34f45e2 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 1ecd552..c5a7ba0 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 2f94ac4..e5ba9ee 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 82b1191..d5bbe67 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 baa3175..fabc22e 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 e605f7b..8bb3187 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 3bb7294..48f952d 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 65681ec..0c10e7a 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 120b174..1020924 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 36c15e9..c4f8781 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 3eb9879..eaa9464 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 fd3c3d9..3fa7916 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 2a996e4..a36c8a5 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 de6f27c..8fccef2 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 2f993f9..e22a2e1 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 03ebb02..98f3c45 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 7c9c5a0..e7bf45d 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 1c3d10e..a8df81f 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 6d864a8..0deb15c 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 72b8f03..2269f50 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 5a7e41c..ac0c9ae 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 aaab6b1..4e50ad1 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 f35df36..c4bf3dc 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 b65a3e8..70d56a1 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 87e0916..d1693ea 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 dd6d243..a0aa45e 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 fae81f8..43d6ffc 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 d264a33..16093d5 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 70b8c7d..5a993dc 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 cc266fa..9511eae 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 542db1b..59e1f2d 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 b40bd41..3fa1046 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 1dc5930..734b632 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 0d9bfd5..9f5ba46 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 7d561e2..9778a85 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 1b2ba2a..2f1879d 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 a795e05..f326e77 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 @@ 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 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``. |