gh-116622: Complete Android documentation (#124259)

Co-authored-by: Russell Keith-Magee <[email protected]> Co-authored-by: T. Wouters <[email protected]> Co-authored-by: Adam Turner <[email protected]>
python · Sep 23, 2024 · e80dd30 · e80dd30
1 parent 27a62e7
commit e80dd30
Show file tree

Hide file tree

Showing 22 changed files with 205 additions and 111 deletions.
diff --git a/Android/README.md b/Android/README.md
@@ -1,13 +1,9 @@
 # Python for Android
 
 These instructions are only needed if you're planning to compile Python for
-Android yourself. Most users should *not* need to do this. If you're looking to
-use Python on Android, one of the following tools will provide a much more
-approachable user experience:
-
-* [Briefcase](https://briefcase.readthedocs.io), from the BeeWare project
-* [Buildozer](https://buildozer.readthedocs.io), from the Kivy project
-* [Chaquopy](https://chaquo.com/chaquopy/)
+Android yourself. Most users should *not* need to do this. Instead, use one of
+the tools listed in `Doc/using/android.rst`, which will provide a much easier
+experience.
 
 
 ## Prerequisites
@@ -89,10 +85,10 @@ The test suite can be run on Linux, macOS, or Windows:
 The test suite can usually be run on a device with 2 GB of RAM, but this is
 borderline, so you may need to increase it to 4 GB. As of Android
 Studio Koala, 2 GB is the default for all emulators, although the user interface
-may indicate otherwise. The effective setting is `hw.ramSize` in
-~/.android/avd/*.avd/hardware-qemu.ini, whereas Android Studio displays the
-value from config.ini. Changing the value in Android Studio will update both of
-these files.
+may indicate otherwise. Locate the emulator's directory under `~/.android/avd`,
+and find `hw.ramSize` in both config.ini and hardware-qemu.ini. Either set these
+manually to the same value, or use the Android Studio Device Manager, which will
+update both files.
 
 Before running the test suite, follow the instructions in the previous section
 to build the architecture you want to test. Then run the test script in one of
@@ -133,3 +129,8 @@ Every time you run `android.py test`, changes in pure-Python files in the
 repository's `Lib` directory will be picked up immediately. Changes in C files,
 and architecture-specific files such as sysconfigdata, will not take effect
 until you re-run `android.py make-host` or `build`.
+
+
+## Using in your own app
+
+See `Doc/using/android.rst`.
diff --git a/Doc/includes/wasm-ios-notavail.rst b/Doc/includes/wasm-ios-notavail.rst
diff --git a/Doc/includes/wasm-mobile-notavail.rst b/Doc/includes/wasm-mobile-notavail.rst
@@ -0,0 +1,6 @@
+.. include for modules that don't work on WASM or mobile platforms
+
+.. availability:: not Android, not iOS, not WASI.
+
+   This module is not supported on :ref:`mobile platforms <mobile-availability>`
+   or :ref:`WebAssembly platforms <wasm-availability>`.
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
@@ -21,7 +21,7 @@ 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
+.. include:: ../includes/wasm-mobile-notavail.rst
 
 .. note::
 

diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
@@ -19,8 +19,6 @@ 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
 
    A tuple containing the exceptions that can be raised by each of the supported
@@ -164,6 +162,8 @@ SQLite backend for the :mod:`dbm` module.
 The files created by :mod:`dbm.sqlite3` can thus be opened by :mod:`sqlite3`,
 or any other SQLite browser, including the SQLite CLI.
 
+.. include:: ../includes/wasm-notavail.rst
+
 .. function:: open(filename, /, flag="r", mode=0o666)
 
    Open an SQLite database.
@@ -207,6 +207,8 @@ functionality like crash tolerance.
    The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
    and can not be used interchangeably.
 
+.. include:: ../includes/wasm-mobile-notavail.rst
+
 .. exception:: error
 
    Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is
@@ -326,6 +328,8 @@ This module can be used with the "classic" NDBM interface or the
    when storing values larger than this limit. Reading such corrupted files can
    result in a hard crash (segmentation fault).
 
+.. include:: ../includes/wasm-mobile-notavail.rst
+
 .. exception:: error
 
    Raised on :mod:`dbm.ndbm`-specific errors, such as I/O errors. :exc:`KeyError` is raised

diff --git a/Doc/library/ensurepip.rst b/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-ios-notavail.rst
+.. include:: ../includes/wasm-mobile-notavail.rst
 
 Command line interface
 ----------------------

diff --git a/Doc/library/grp.rst b/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 WASI, not iOS.
+.. availability:: Unix, not WASI, not Android, 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

diff --git a/Doc/library/intro.rst b/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 and iOS, both of which build on a Unix core.
+  supported on macOS, iOS and Android, all 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
@@ -120,43 +120,57 @@ DOM APIs as well as limited networking capabilities with JavaScript's
 .. _Pyodide: https://pyodide.org/
 .. _PyScript: https://pyscript.net/
 
+.. _mobile-availability:
 .. _iOS-availability:
 
-iOS
----
+Mobile platforms
+----------------
 
-iOS is, in most respects, a POSIX operating system. File I/O, socket handling,
+Android and iOS are, in most respects, POSIX operating systems. 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
+there are several major differences:
+
+* Mobile platforms can only use Python in "embedded" mode. There is no Python
+  REPL, and no ability to use separate executables such as :program:`python` or
+  :program:`pip`. To add Python code to your mobile app, you must use
+  the :ref:`Python embedding API <embedding>`. For more details, see
+  :ref:`using-android` and :ref:`using-ios`.
+
+* Subprocesses:
+
+  * On Android, creating subprocesses is possible but `officially unsupported
+    <https://issuetracker.google.com/issues/128554619#comment4>`__.
+    In particular, Android does not support any part of the System V IPC API,
+    so :mod:`multiprocessing` is not available.
+
+  * An iOS app cannot use any form of subprocessing, multiprocessing, 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.
+
+* Mobile 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``.
+* Console input and output:
+
+  * On Android, the native ``stdout`` and ``stderr`` are not connected to
+    anything, so Python installs its own streams which redirect messages to the
+    system log. These can be seen under the tags ``python.stdout`` and
+    ``python.stderr`` respectively.
+
+  * iOS apps have a limited concept of console 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``.
+  * Mobile apps have no usable ``stdin`` at all. While apps can display an on-screen
+    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.
+    As a result, Python modules that involve console manipulation (such as
+    :mod:`curses` and :mod:`readline`) are not available on mobile platforms.
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
@@ -8,7 +8,7 @@
 
 --------------
 
-.. include:: ../includes/wasm-ios-notavail.rst
+.. include:: ../includes/wasm-mobile-notavail.rst
 
 Introduction
 ------------