gh-114099: Add documentation for iOS platform (GH-117057)

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Jacob Coffee <[email protected]>
Co-authored-by: Malcolm Smith <[email protected]>
Co-authored-by: Ned Deily <[email protected]>

Author: 5 people

Doc/includes/wasm-ios-notavail.rst

@@ -0,0 +1,8 @@
+.. include for modules that don't work on WASM or iOS
+
+.. availability:: not WASI, not iOS.
+
+   This module does not work or is not available on WebAssembly platforms, or
+   on iOS. See :ref:`wasm-availability` for more information on WASM
+   availability; see :ref:`iOS-availability` for more information on iOS
+   availability.

Doc/includes/wasm-notavail.rst

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

Doc/library/curses.rst

@@ -21,6 +21,8 @@ for Windows, DOS, and possibly other systems as well.  This extension module is
 designed to match the API of ncurses, an open-source curses library hosted on
 Linux and the BSD variants of Unix.
 
+.. include:: ../includes/wasm-ios-notavail.rst
+
 .. note::
 
    Whenever the documentation mentions a *character* it can be specified

Doc/library/dbm.rst

@@ -19,6 +19,7 @@ slow-but-simple implementation in module :mod:`dbm.dumb` will be used.  There
 is a `third party interface <https://www.jcea.es/programacion/pybsddb.htm>`_ to
 the Oracle Berkeley DB.
 
+.. include:: ../includes/wasm-ios-notavail.rst
 
 .. exception:: error
 
@@ -455,4 +456,3 @@ The :mod:`!dbm.dumb` module defines the following:
    .. method:: dumbdbm.close()
 
       Close the database.
-

Doc/library/ensurepip.rst

@@ -38,7 +38,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
+.. include:: ../includes/wasm-ios-notavail.rst
 
 Command line interface
 ----------------------

Doc/library/fcntl.rst

@@ -18,7 +18,7 @@ interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines.
 See the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix manual pages
 for full details.
 
-.. availability:: Unix, not Emscripten, not WASI.
+.. availability:: Unix, not WASI.
 
 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

Doc/library/grp.rst

@@ -10,7 +10,7 @@
 This module provides access to the Unix group database. It is available on all
 Unix versions.
 
-.. availability:: Unix, not Emscripten, not WASI.
+.. availability:: Unix, not WASI, not iOS.
 
 Group database entries are reported as a tuple-like object, whose attributes
 correspond to the members of the ``group`` structure (Attribute field below, see

Doc/library/intro.rst

@@ -58,7 +58,7 @@ Notes on availability
   operating system.
 
 * If not separately noted, all functions that claim "Availability: Unix" are
-  supported on macOS, which builds on a Unix core.
+  supported on macOS and iOS, both of which build on a Unix core.
 
 * If an availability note contains both a minimum Kernel version and a minimum
   libc version, then both conditions must hold. For example a feature with note
@@ -119,3 +119,44 @@ DOM APIs as well as limited networking capabilities with JavaScript's
 .. _wasmtime: https://wasmtime.dev/
 .. _Pyodide: https://pyodide.org/
 .. _PyScript: https://pyscript.net/
+
+.. _iOS-availability:
+
+iOS
+---
+
+iOS is, in most respects, a POSIX operating system. File I/O, socket handling,
+and threading all behave as they would on any POSIX operating system. However,
+there are several major differences between iOS and other POSIX systems.
+
+* iOS can only use Python in "embedded" mode. There is no Python REPL, and no
+  ability to execute binaries that are part of the normal Python developer
+  experience, such as :program:`pip`. To add Python code to your iOS app, you must use
+  the :ref:`Python embedding API <embedding>` to add a Python interpreter to an
+  iOS app created with Xcode. See the :ref:`iOS usage guide <using-ios>` for
+  more details.
+
+* An iOS app cannot use any form of subprocessing, background processing, or
+  inter-process communication. If an iOS app attempts to create a subprocess,
+  the process creating the subprocess will either lock up, or crash. An iOS app
+  has no visibility of other applications that are running, nor any ability to
+  communicate with other running applications, outside of the iOS-specific APIs
+  that exist for this purpose.
+
+* iOS apps have limited access to modify system resources (such as the system
+  clock). These resources will often be *readable*, but attempts to modify
+  those resources will usually fail.
+
+* iOS apps have a limited concept of console input and output. ``stdout`` and
+  ``stderr`` *exist*, and content written to ``stdout`` and ``stderr`` will be
+  visible in logs when running in Xcode, but this content *won't* be recorded
+  in the system log. If a user who has installed your app provides their app
+  logs as a diagnostic aid, they will not include any detail written to
+  ``stdout`` or ``stderr``.
+
+  iOS apps have no concept of  ``stdin`` at all. While iOS apps can have a
+  keyboard, this is a software feature, not something that is attached to
+  ``stdin``.
+
+  As a result, Python library that involve console manipulation (such as
+  :mod:`curses` and :mod:`readline`) are not available on iOS.

Doc/library/multiprocessing.rst

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