]> git.ipfire.org Git - thirdparty/Python/cpython.git/commitdiff
[3.13] gh-116622: Complete Android documentation (GH-124259) (#124395)
authorMiss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Tue, 24 Sep 2024 00:13:45 +0000 (02:13 +0200)
committerGitHub <noreply@github.com>
Tue, 24 Sep 2024 00:13:45 +0000 (00:13 +0000)
gh-116622: Complete Android documentation (GH-124259)
(cherry picked from commit e80dd3035fb805716bc49f9e7e9cab5f83614661)

Co-authored-by: Malcolm Smith <smith@chaquo.com>
Co-authored-by: Russell Keith-Magee <russell@keith-magee.com>
Co-authored-by: T. Wouters <thomas@python.org>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
22 files changed:
Android/README.md
Doc/includes/wasm-ios-notavail.rst [deleted file]
Doc/includes/wasm-mobile-notavail.rst [new file with mode: 0644]
Doc/library/curses.rst
Doc/library/dbm.rst
Doc/library/ensurepip.rst
Doc/library/grp.rst
Doc/library/intro.rst
Doc/library/multiprocessing.rst
Doc/library/os.rst
Doc/library/readline.rst
Doc/library/socket.rst
Doc/library/subprocess.rst
Doc/library/time.rst
Doc/library/venv.rst
Doc/library/webbrowser.rst
Doc/using/android.rst [new file with mode: 0644]
Doc/using/index.rst
Doc/using/ios.rst
Doc/whatsnew/3.13.rst
Misc/ACKS
Misc/NEWS.d/next/Documentation/2024-09-19-19-33-25.gh-issue-116622.M65UZ6.rst [new file with mode: 0644]

index bae9150ef057acc34321523b5b7735e960da1187..6012677257743231fb214df3ed979437a33bb1e1 100644 (file)
@@ -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
@@ -87,10 +83,10 @@ and copy it over.
 The test suite can usually be run on a device with 2 GB of RAM, though for some
 configurations or test orders you may need to increase this. 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
@@ -131,3 +127,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
deleted file mode 100644 (file)
index c820665..0000000
+++ /dev/null
@@ -1,8 +0,0 @@
-.. 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.
diff --git a/Doc/includes/wasm-mobile-notavail.rst b/Doc/includes/wasm-mobile-notavail.rst
new file mode 100644 (file)
index 0000000..725b0f7
--- /dev/null
@@ -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>`.
index 91ea6150fb15ba34819fad95510f5ecbfba609a1..6c7fc721a3e0fbd1d3294513519880b514770f53 100644 (file)
@@ -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::
 
index 77148a558d19096a3ecafacd863a8180137032cc..6c659ea52ad821527b01c8ca57faf96445f010e7 100644 (file)
@@ -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
index 518a2940edcf69577b23e4eeaa8fc0cf2801d318..8dfb7ad9c95c3e26d857149df4519c8e5a464ede 100644 (file)
@@ -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
 ----------------------
index 30caea328baa79e3590d916a0c7a83bd81e0bb10..d1c7f22a2097803a0957d357934e6d7241350668 100644 (file)
@@ -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
index ffc8939d21157dee611a04c6e0df777f34a9d055..8f76044be488cdaa4a4fed1b21df440a7b017029 100644 (file)
@@ -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.
index 9fa76c4ce59d001fe9676ca057b2396b8133575f..80d6e4dae24463bcc5e9fda39b7020f91b881a78 100644 (file)
@@ -8,7 +8,7 @@
 
 --------------
 
-.. include:: ../includes/wasm-ios-notavail.rst
+.. include:: ../includes/wasm-mobile-notavail.rst
 
 Introduction
 ------------
index 3ec91ecb9bc66a12f9834539ba677ee82d9d3201..c8bbb5eb3abf6c48836c7ae3c28677390948c4cd 100644 (file)
@@ -34,8 +34,8 @@ 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, and on iOS, large parts of the :mod:`os` module are
-  not available or behave differently. API related to processes (e.g.
+* On WebAssembly platforms, Android and iOS, large parts of the :mod:`os` module are
+  not available or behave differently. APIs related to processes (e.g.
   :func:`~os.fork`, :func:`~os.execve`) and resources (e.g. :func:`~os.nice`)
   are not available. Others like :func:`~os.getuid` and :func:`~os.getpid` are
   emulated or stubs. WebAssembly platforms also lack support for signals (e.g.
@@ -542,7 +542,7 @@ process and user.
    the groups of which the specified username is a member, plus the specified
    group id.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not Android.
 
    .. versionadded:: 3.2
 
@@ -576,21 +576,21 @@ process and user.
 
    Set the current process's effective group id.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not Android.
 
 
 .. function:: seteuid(euid, /)
 
    Set the current process's effective user id.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not Android.
 
 
 .. function:: setgid(gid, /)
 
    Set the current process' group id.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not Android.
 
 
 .. function:: setgroups(groups, /)
@@ -684,14 +684,14 @@ process and user.
 
    Set the current process's real and effective group ids.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not Android.
 
 
 .. function:: setresgid(rgid, egid, sgid, /)
 
    Set the current process's real, effective, and saved group ids.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not Android.
 
    .. versionadded:: 3.2
 
@@ -700,7 +700,7 @@ process and user.
 
    Set the current process's real, effective, and saved user ids.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not Android.
 
    .. versionadded:: 3.2
 
@@ -709,7 +709,7 @@ process and user.
 
    Set the current process's real and effective user ids.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not Android.
 
 
 .. function:: getsid(pid, /)
@@ -732,7 +732,7 @@ process and user.
 
    Set the current process's user id.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not Android.
 
 
 .. placed in this section since it relates to errno.... a little weak
@@ -2178,7 +2178,7 @@ features:
 
    Change the root directory of the current process to *path*.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not Android.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -4284,7 +4284,7 @@ to be ignored.
 
    .. audit-event:: os.exec path,args,env os.execl
 
-   .. availability:: Unix, Windows, not WASI, not iOS.
+   .. availability:: Unix, Windows, not WASI, not Android, not iOS.
 
    .. versionchanged:: 3.3
       Added support for specifying *path* as an open file descriptor
@@ -4487,7 +4487,7 @@ written in Python, such as a mail server's external command delivery program.
       for technical details of why we're surfacing this longstanding
       platform compatibility problem to developers.
 
-   .. availability:: POSIX, not WASI, not iOS.
+   .. availability:: POSIX, not WASI, not Android, not iOS.
 
 
 .. function:: forkpty()
@@ -4514,7 +4514,7 @@ written in Python, such as a mail server's external command delivery program.
       threads, this now raises a :exc:`DeprecationWarning`. See the
       longer explanation on :func:`os.fork`.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. function:: kill(pid, sig, /)
@@ -4623,7 +4623,7 @@ 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 WASI, not iOS.
+   .. availability:: not WASI, not Android, not iOS.
 
    .. note::
       The :ref:`Python UTF-8 Mode <utf8-mode>` affects encodings used
@@ -4731,7 +4731,7 @@ written in Python, such as a mail server's external command delivery program.
       ``os.POSIX_SPAWN_CLOSEFROM`` is available on platforms where
       :c:func:`!posix_spawn_file_actions_addclosefrom_np` exists.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 .. function:: posix_spawnp(path, argv, env, *, file_actions=None, \
                           setpgroup=None, resetids=False, setsid=False, setsigmask=(), \
@@ -4747,7 +4747,7 @@ written in Python, such as a mail server's external command delivery program.
 
    .. versionadded:: 3.8
 
-   .. availability:: POSIX, not WASI, not iOS.
+   .. availability:: POSIX, not WASI, not Android, not iOS.
 
       See :func:`posix_spawn` documentation.
 
@@ -4780,7 +4780,7 @@ written in Python, such as a mail server's external command delivery program.
 
    There is no way to unregister a function.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
    .. versionadded:: 3.7
 
@@ -4849,7 +4849,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, not WASI, not iOS.
+   .. availability:: Unix, Windows, not WASI, not Android, not iOS.
 
       :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
       and :func:`spawnvpe` are not available on Windows.  :func:`spawnle` and
@@ -4973,7 +4973,7 @@ written in Python, such as a mail server's external command delivery program.
 
    .. audit-event:: os.system command os.system
 
-   .. availability:: Unix, Windows, not WASI, not iOS.
+   .. availability:: Unix, Windows, not WASI, not Android, not iOS.
 
 
 .. function:: times()
@@ -5017,7 +5017,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, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
    .. seealso::
 
@@ -5051,7 +5051,7 @@ written in Python, such as a mail server's external command delivery program.
    Otherwise, if there are no matching children
    that could be waited for, :exc:`ChildProcessError` is raised.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
    .. versionadded:: 3.3
 
@@ -5092,7 +5092,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, Windows, not WASI, not iOS.
+   .. availability:: Unix, Windows, not WASI, not Android, not iOS.
 
    .. versionchanged:: 3.5
       If the system call is interrupted and the signal handler does not raise an
@@ -5112,7 +5112,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, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. function:: wait4(pid, options)
@@ -5126,7 +5126,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, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. data:: P_PID
@@ -5143,7 +5143,7 @@ written in Python, such as a mail server's external command delivery program.
    * :data:`!P_PIDFD` - wait for the child identified by the file descriptor
      *id* (a process file descriptor created with :func:`pidfd_open`).
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
    .. note:: :data:`!P_PIDFD` is only available on Linux >= 5.4.
 
@@ -5158,7 +5158,7 @@ written in Python, such as a mail server's external command delivery program.
    :func:`waitid` causes child processes to be reported if they have been
    continued from a job control stop since they were last reported.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. data:: WEXITED
@@ -5169,7 +5169,7 @@ written in Python, such as a mail server's external command delivery program.
    The other ``wait*`` functions always report children that have terminated,
    so this option is not available for them.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
    .. versionadded:: 3.3
 
@@ -5181,7 +5181,7 @@ written in Python, such as a mail server's external command delivery program.
 
    This option is not available for the other ``wait*`` functions.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
    .. versionadded:: 3.3
 
@@ -5194,7 +5194,7 @@ written in Python, such as a mail server's external command delivery program.
 
    This option is not available for :func:`waitid`.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. data:: WNOHANG
@@ -5203,7 +5203,7 @@ written in Python, such as a mail server's external command delivery program.
    :func:`waitid` to return right away if no child process status is available
    immediately.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. data:: WNOWAIT
@@ -5213,7 +5213,7 @@ written in Python, such as a mail server's external command delivery program.
 
    This option is not available for the other ``wait*`` functions.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. data:: CLD_EXITED
@@ -5226,7 +5226,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, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
    .. versionadded:: 3.3
 
@@ -5261,7 +5261,7 @@ 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 WASI, not iOS.
+   .. availability:: Unix, Windows, not WASI, not Android, not iOS.
 
    .. versionadded:: 3.9
 
@@ -5277,7 +5277,7 @@ used to determine the disposition of a process.
 
    This function should be employed only if :func:`WIFSIGNALED` is true.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. function:: WIFCONTINUED(status)
@@ -5288,7 +5288,7 @@ used to determine the disposition of a process.
 
    See :data:`WCONTINUED` option.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. function:: WIFSTOPPED(status)
@@ -5300,14 +5300,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, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 .. function:: WIFSIGNALED(status)
 
    Return ``True`` if the process was terminated by a signal, otherwise return
    ``False``.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. function:: WIFEXITED(status)
@@ -5316,7 +5316,7 @@ used to determine the disposition of a process.
    by calling ``exit()`` or ``_exit()``, or by returning from ``main()``;
    otherwise return ``False``.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. function:: WEXITSTATUS(status)
@@ -5325,7 +5325,7 @@ used to determine the disposition of a process.
 
    This function should be employed only if :func:`WIFEXITED` is true.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. function:: WSTOPSIG(status)
@@ -5334,7 +5334,7 @@ used to determine the disposition of a process.
 
    This function should be employed only if :func:`WIFSTOPPED` is true.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 .. function:: WTERMSIG(status)
@@ -5343,7 +5343,7 @@ used to determine the disposition of a process.
 
    This function should be employed only if :func:`WIFSIGNALED` is true.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not Android, not iOS.
 
 
 Interface to the scheduler
index d03b71597130cfed66102c9469568fe578384912..4a04205663258c8ddc57eaf9ce9776cbeee74c9d 100644 (file)
@@ -24,7 +24,7 @@ in the GNU Readline manual for information about the format and
 allowable constructs of that file, and the capabilities of the
 Readline library in general.
 
-.. include:: ../includes/wasm-ios-notavail.rst
+.. include:: ../includes/wasm-mobile-notavail.rst
 
 .. note::
 
index d0791244d176d1ad5e86e9127598938f740a756f..dc1baa28e1c7ce2873ce6e153e7c7053b2fcda0a 100644 (file)
@@ -1272,7 +1272,7 @@ The :mod:`socket` module also offers various network-related services:
 
    .. audit-event:: socket.sethostname name socket.sethostname
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Android.
 
    .. versionadded:: 3.3
 
index cd95754bc36897f289c307b89883d052792b4a8b..59c98e867ff42d07e290aef3c9ee124522a73a1b 100644 (file)
@@ -25,7 +25,7 @@ modules and functions can be found in the following sections.
 
    :pep:`324` -- PEP proposing the subprocess module
 
-.. include:: ../includes/wasm-ios-notavail.rst
+.. include:: ../includes/wasm-mobile-notavail.rst
 
 Using the :mod:`subprocess` Module
 ----------------------------------
index 24575105df8ae0260cbbc9f1c4f1da327dae8bcc..a0bf13fc0a357705b3737889de4c12404e7b3187 100644 (file)
@@ -193,7 +193,7 @@ Functions
    Use :func:`clock_settime_ns` to avoid the precision loss caused by the
    :class:`float` type.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Android, not iOS.
 
    .. versionadded:: 3.3
 
@@ -202,7 +202,7 @@ Functions
 
    Similar to :func:`clock_settime` but set time with nanoseconds.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Android, not iOS.
 
    .. versionadded:: 3.7
 
index fff1075c2473eb042e58da786575c56d8232289f..cf6c5437be4fd1d815a1066e3d728eac977f9431 100644 (file)
@@ -56,7 +56,7 @@ See :pep:`405` for more background on Python virtual environments.
    `Python Packaging User Guide: Creating and using virtual environments
    <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments>`__
 
-.. include:: ../includes/wasm-ios-notavail.rst
+.. include:: ../includes/wasm-mobile-notavail.rst
 
 Creating virtual environments
 -----------------------------
index 4a155974dbd2f5ddd8d8e5348a3d6533b7295678..2d19c514ce43b698348069c36f6d70b8950cce40 100644 (file)
@@ -51,7 +51,7 @@ The options are, naturally, mutually exclusive.  Usage example::
 
    python -m webbrowser -t "https://www.python.org"
 
-.. include:: ../includes/wasm-notavail.rst
+.. availability:: not WASI, not Android.
 
 The following exception is defined:
 
diff --git a/Doc/using/android.rst b/Doc/using/android.rst
new file mode 100644 (file)
index 0000000..957705f
--- /dev/null
@@ -0,0 +1,65 @@
+.. _using-android:
+
+=======================
+Using Python on Android
+=======================
+
+Python on Android is unlike Python on desktop platforms. On a desktop platform,
+Python is generally installed as a system resource that can be used by any user
+of that computer. Users then interact with Python by running a :program:`python`
+executable and entering commands at an interactive prompt, or by running a
+Python script.
+
+On Android, there is no concept of installing as a system resource. The only unit
+of software distribution is an "app". There is also no console where you could
+run a :program:`python` executable, or interact with a Python REPL.
+
+As a result, the only way you can use Python on Android is in embedded mode – that
+is, by writing a native Android application, embedding a Python interpreter
+using ``libpython``, and invoking Python code using the :ref:`Python embedding
+API <embedding>`. The full Python interpreter, the standard library, and all
+your Python code is then packaged into your app for its own private use.
+
+The Python standard library has some notable omissions and restrictions on
+Android. See the :ref:`API availability guide <mobile-availability>` for
+details.
+
+Adding Python to an Android app
+-------------------------------
+
+These instructions are only needed if you're planning to compile Python for
+Android yourself. Most users should *not* need to do this. Instead, use one of
+the following tools, which will provide a much easier experience:
+
+* `Briefcase <https://briefcase.readthedocs.io>`__, from the BeeWare project
+* `Buildozer <https://buildozer.readthedocs.io>`__, from the Kivy project
+* `Chaquopy <https://chaquo.com/chaquopy>`__
+* `pyqtdeploy <https://www.riverbankcomputing.com/static/Docs/pyqtdeploy/>`__
+* `Termux <https://termux.dev/en/>`__
+
+If you're sure you want to do all of this manually, read on. You can use the
+:source:`testbed app <Android/testbed>` as a guide; each step below contains a
+link to the relevant file.
+
+* Build Python by following the instructions in :source:`Android/README.md`.
+
+* Add code to your :source:`build.gradle <Android/testbed/app/build.gradle.kts>`
+  file to copy the following items into your project. All except your own Python
+  code can be copied from ``cross-build/HOST/prefix/lib``:
+
+  * In your JNI libraries:
+
+    * ``libpython*.*.so``
+    * ``lib*_python.so`` (external libraries such as OpenSSL)
+
+  * In your assets:
+
+    * ``python*.*`` (the Python standard library)
+    * ``python*.*/site-packages`` (your own Python code)
+
+* Add code to your app to :source:`extract the assets to the filesystem
+  <Android/testbed/app/src/main/java/org/python/testbed/MainActivity.kt>`.
+
+* Add code to your app to :source:`start Python in embedded mode
+  <Android/testbed/app/src/main/c/main_activity.c>`. This will need to be C code
+  called via JNI.
index f55a12f1ab8a0db314ce766bce584d60ae4b2057..90fdfc0bec0583129ea4256e7ac223077e0a973b 100644 (file)
@@ -12,11 +12,13 @@ interpreter and things that make working with Python easier.
 
 .. toctree::
    :numbered:
+   :maxdepth: 2
 
    cmdline.rst
    unix.rst
    configure.rst
    windows.rst
    mac.rst
+   android.rst
    ios.rst
    editors.rst
index 455221c8c3180e1757bf6703e1da6259d4472244..4d4eb2031ee980b858d5666bfc7f59878a6b9ca7 100644 (file)
@@ -63,7 +63,7 @@ Standard library availability
 -----------------------------
 
 The Python standard library has some notable omissions and restrictions on
-iOS. See the :ref:`API availability guide for iOS <iOS-availability>` for
+iOS. See the :ref:`API availability guide for iOS <mobile-availability>` for
 details.
 
 Binary extension modules
index e5f9db9f4f17b0c7cc1853ccff54985747e3f1d4..6cd00f3718feb9d03c0b8fb6e549c4ef0034722d 100644 (file)
@@ -171,7 +171,8 @@ Platform support:
 
 * :pep:`730`: Apple's iOS is now an :ref:`officially supported platform
   <whatsnew313-platform-support>`, at :pep:`tier 3 <11#tier-3>`.
-  Official Android support (:pep:`738`) is also in the works.
+* :pep:`738`: Android is now an :ref:`officially supported platform
+  <whatsnew313-platform-support>`, at :pep:`tier 3 <11#tier-3>`.
 * ``wasm32-wasi`` is now supported as a :pep:`tier 2 <11#tier-2>` platform.
 * ``wasm32-emscripten`` is no longer an officially supported platform.
 
@@ -479,8 +480,10 @@ is not a tier 3 supported platform, but will have best-effort support.
 (PEP written and implementation contributed by Russell Keith-Magee in
 :gh:`114099`.)
 
-:pep:`738`: Android support is being actively worked on,
-but the platform is not yet officially supported.
+:pep:`738`: Android is now a :pep:`11` supported platform, with the
+``aarch64-linux-android`` and ``x86_64-linux-android`` targets at tier 3.
+The 32-bit targets ``arm-linux-androideabi`` and ``i686-linux-android``
+are not tier 3 supported platforms, but will have best-effort support.
 (PEP written and implementation contributed by Malcolm Smith in
 :gh:`116622`.)
 
@@ -2515,6 +2518,11 @@ Build Changes
   (:ref:`PEP 730 <whatsnew313-platform-support>` written
   and implementation contributed by Russell Keith-Magee in :gh:`114099`.)
 
+* ``aarch64-linux-android`` and ``x86_64-linux-android`` are both
+  now :pep:`11` tier 3 platforms.
+  (:ref:`PEP 738 <whatsnew313-platform-support>` written
+  and implementation contributed by Malcolm Smith in :gh:`116622`.)
+
 * ``wasm32-wasi`` is now a :pep:`11` tier 2 platform.
   (Contributed by Brett Cannon in :gh:`115192`.)
 
index 694654e555aa33cde9f3ada1df4697a5801d8672..dff73bba0136987487d781ac2baec8528c73fc06 100644 (file)
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1742,6 +1742,7 @@ Christopher Smith
 Eric V. Smith
 Ethan H. Smith
 Gregory P. Smith
+Malcolm Smith
 Mark Smith
 Nathaniel J. Smith
 Roy Smith
diff --git a/Misc/NEWS.d/next/Documentation/2024-09-19-19-33-25.gh-issue-116622.M65UZ6.rst b/Misc/NEWS.d/next/Documentation/2024-09-19-19-33-25.gh-issue-116622.M65UZ6.rst
new file mode 100644 (file)
index 0000000..f047a8c
--- /dev/null
@@ -0,0 +1 @@
+Add an Android platform guide, and flag modules not available on Android.