Skip to content

Commit e3b6ff1

Browse files
tiranmerwokmdboomezio-melottiCAM-Gerlach
authored
gh-95451: Update docs for wasm32-emscripten and -wasi platforms (GH-95452)
Co-authored-by: Éric <[email protected]> Co-authored-by: Michael Droettboom <[email protected]> Co-authored-by: Ezio Melotti <[email protected]> Co-authored-by: CAM Gerlach <[email protected]>
1 parent 75a6441 commit e3b6ff1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+322
-105
lines changed

‎Doc/includes/wasm-notavail.rst

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

‎Doc/library/asynchat.rst

+1
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ Typically an :class:`asyncore.dispatcher` server channel generates new
3434
:class:`asynchat.async_chat` channel objects as it receives incoming
3535
connection requests.
3636

37+
.. include:: ../includes/wasm-notavail.rst
3738

3839
.. class:: async_chat()
3940

‎Doc/library/asyncio.rst

+1
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ Additionally, there are **low-level** APIs for
5656
* :ref:`bridge <asyncio-futures>` callback-based libraries and code
5757
with async/await syntax.
5858

59+
.. include:: ../includes/wasm-notavail.rst
5960

6061
.. We use the "rubric" directive here to avoid creating
6162
the "Reference" subsection in the TOC.

‎Doc/library/asyncore.rst

+2
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@
2828
This module provides the basic infrastructure for writing asynchronous socket
2929
service clients and servers.
3030

31+
.. include:: ../includes/wasm-notavail.rst
32+
3133
There are only two ways to have a program on a single processor do "more than
3234
one thing at a time." Multi-threaded programming is the simplest and most
3335
popular way to do it, but there is another very different technique, that lets

‎Doc/library/cgi.rst

+1
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ size of a POST request. POST requests larger than this size will result in a
3737
:exc:`ValueError` being raised during parsing. The default value of this
3838
variable is ``0``, meaning the request size is unlimited.
3939

40+
.. include:: ../includes/wasm-notavail.rst
4041

4142
Introduction
4243
------------

‎Doc/library/compileall.rst

+1
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ This module can be used to create the cached byte-code files at library
1414
installation time, which makes them available for use even by users who don't
1515
have write permission to the library directories.
1616

17+
.. include:: ../includes/wasm-notavail.rst
1718

1819
Command-line use
1920
----------------

‎Doc/library/concurrent.futures.rst

+1
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ The asynchronous execution can be performed with threads, using
1919
:class:`ProcessPoolExecutor`. Both implement the same interface, which is
2020
defined by the abstract :class:`Executor` class.
2121

22+
.. include:: ../includes/wasm-notavail.rst
2223

2324
Executor Objects
2425
----------------

‎Doc/library/crypt.rst

+2
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ this module.
3838

3939
.. availability:: Unix, not VxWorks.
4040

41+
.. include:: ../includes/wasm-notavail.rst
42+
4143
Hashing Methods
4244
---------------
4345

‎Doc/library/ensurepip.rst

+1
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ when creating a virtual environment) or after explicitly uninstalling
3636
:pep:`453`: Explicit bootstrapping of pip in Python installations
3737
The original rationale and specification for this module.
3838

39+
.. include:: ../includes/wasm-notavail.rst
3940

4041
Command line interface
4142
----------------------

‎Doc/library/fcntl.rst

+2
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. For a
1818
complete description of these calls, see :manpage:`fcntl(2)` and
1919
:manpage:`ioctl(2)` Unix manual pages.
2020

21+
.. include:: ../includes/wasm-notavail.rst
22+
2123
All functions in this module take a file descriptor *fd* as their first
2224
argument. This can be an integer file descriptor, such as returned by
2325
``sys.stdin.fileno()``, or an :class:`io.IOBase` object, such as ``sys.stdin``

‎Doc/library/ftplib.rst

+2
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ as mirroring other FTP servers. It is also used by the module
2121

2222
The default encoding is UTF-8, following :rfc:`2640`.
2323

24+
.. include:: ../includes/wasm-notavail.rst
25+
2426
Here's a sample session using the :mod:`ftplib` module::
2527

2628
>>> from ftplib import FTP

‎Doc/library/getpass.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,9 @@
1212

1313
--------------
1414

15-
The :mod:`getpass` module provides two functions:
15+
.. include:: ../includes/wasm-notavail.rst
1616

17+
The :mod:`getpass` module provides two functions:
1718

1819
.. function:: getpass(prompt='Password: ', stream=None)
1920

‎Doc/library/grp.rst

+2
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
This module provides access to the Unix group database. It is available on all
1111
Unix versions.
1212

13+
.. include:: ../includes/wasm-notavail.rst
14+
1315
Group database entries are reported as a tuple-like object, whose attributes
1416
correspond to the members of the ``group`` structure (Attribute field below, see
1517
``<grp.h>``):

‎Doc/library/http.client.rst

+2
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ HTTPS protocols. It is normally not used directly --- the module
2828
HTTPS support is only available if Python was compiled with SSL support
2929
(through the :mod:`ssl` module).
3030

31+
.. include:: ../includes/wasm-notavail.rst
32+
3133
The module provides the following classes:
3234

3335

‎Doc/library/http.server.rst

+2
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ This module defines classes for implementing HTTP servers.
2222
:mod:`http.server` is not recommended for production. It only implements
2323
:ref:`basic security checks <http.server-security>`.
2424

25+
.. include:: ../includes/wasm-notavail.rst
26+
2527
One class, :class:`HTTPServer`, is a :class:`socketserver.TCPServer` subclass.
2628
It creates and listens at the HTTP socket, dispatching the requests to a
2729
handler. Code to create and run the server looks like this::

‎Doc/library/imaplib.rst

+2
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ implement a large subset of the IMAP4rev1 client protocol as defined in
2626
:rfc:`2060`. It is backward compatible with IMAP4 (:rfc:`1730`) servers, but
2727
note that the ``STATUS`` command is not supported in IMAP4.
2828

29+
.. include:: ../includes/wasm-notavail.rst
30+
2931
Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
3032
base class:
3133

‎Doc/library/intro.rst

+55
Original file line numberDiff line numberDiff line change
@@ -64,3 +64,58 @@ Notes on availability
6464
libc version, then both conditions must hold. For example a feature with note
6565
*Availability: Linux >= 3.17 with glibc >= 2.27* requires both Linux 3.17 or
6666
newer and glibc 2.27 or newer.
67+
68+
.. _wasm-availability:
69+
70+
WebAssembly platforms
71+
---------------------
72+
73+
The `WebAssembly`_ platforms ``wasm32-emscripten`` (`Emscripten`_) and
74+
``wasm32-wasi`` (`WASI`_) provide a subset of POSIX APIs. WebAssembly runtimes
75+
and browsers are sandboxed and have limited access to the host and external
76+
resources. Any Python standard library module that uses processes, threading,
77+
networking, signals, or other forms of inter-process communication (IPC), is
78+
either not available or may not work as on other Unix-like systems. File I/O,
79+
file system, and Unix permission-related functions are restricted, too.
80+
Emscripten does not permit blocking I/O. Other blocking operations like
81+
:func:`~time.sleep` block the browser event loop.
82+
83+
The properties and behavior of Python on WebAssembly platforms depend on the
84+
`Emscripten`_-SDK or `WASI`_-SDK version, WASM runtimes (browser, NodeJS,
85+
`wasmtime`_), and Python build time flags. WebAssembly, Emscripten, and WASI
86+
are evolving standards; some features like networking may be
87+
supported in the future.
88+
89+
For Python in the browser, users should consider `Pyodide`_ or `PyScript`_.
90+
PyScript is built on top of Pyodide, which itself is built on top of
91+
CPython and Emscripten. Pyodide provides access to browsers' JavaScript and
92+
DOM APIs as well as limited networking capabilities with JavaScript's
93+
``XMLHttpRequest`` and ``Fetch`` APIs.
94+
95+
* Process-related APIs are not available or always fail with an error. That
96+
includes APIs that spawn new processes (:func:`~os.fork`,
97+
:func:`~os.execve`), wait for processes (:func:`~os.waitpid`), send signals
98+
(:func:`~os.kill`), or otherwise interact with processes. The
99+
:mod:`subprocess` is importable but does not work.
100+
101+
* The :mod:`socket` module is available, but is limited and behaves
102+
differently from other platforms. On Emscripten, sockets are always
103+
non-blocking and require additional JavaScript code and helpers on the
104+
server to proxy TCP through WebSockets; see `Emscripten Networking`_
105+
for more information. WASI snapshot preview 1 only permits sockets from an
106+
existing file descriptor.
107+
108+
* Some functions are stubs that either don't do anything and always return
109+
hardcoded values.
110+
111+
* Functions related to file descriptors, file permissions, file ownership, and
112+
links are limited and don't support some operations. For example, WASI does
113+
not permit symlinks with absolute file names.
114+
115+
.. _WebAssembly: https://webassembly.org/
116+
.. _Emscripten: https://emscripten.org/
117+
.. _Emscripten Networking: https://emscripten.org/docs/porting/networking.html>
118+
.. _WASI: https://wasi.dev/
119+
.. _wasmtime: https://wasmtime.dev/
120+
.. _Pyodide: https://pyodide.org/
121+
.. _PyScript: https://pyscript.net/

‎Doc/library/mmap.rst

+2
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66

77
--------------
88

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

‎Doc/library/multiprocessing.rst

+2
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88

99
--------------
1010

11+
.. include:: ../includes/wasm-notavail.rst
12+
1113
Introduction
1214
------------
1315

‎Doc/library/nis.rst

+2
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ central administration of several hosts.
2121

2222
Because NIS exists only on Unix systems, this module is only available for Unix.
2323

24+
.. include:: ../includes/wasm-notavail.rst
25+
2426
The :mod:`nis` module defines the following functions:
2527

2628

‎Doc/library/nntplib.rst

+2
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ the Network News Transfer Protocol. It can be used to implement a news reader
3838
or poster, or automated news processors. It is compatible with :rfc:`3977`
3939
as well as the older :rfc:`977` and :rfc:`2980`.
4040

41+
.. include:: ../includes/wasm-notavail.rst
42+
4143
Here are two small examples of how it can be used. To list some statistics
4244
about a newsgroup and print the subjects of the last 10 articles::
4345

0 commit comments

Comments
 (0)