Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

gh-116622: Complete Android documentation (#124259) 

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>
This commit is contained in:
Malcolm Smith 2024-09-24 00:09:53 +01:00 committed by GitHub
parent 27a62e7371
commit e80dd3035f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
22 changed files with 202 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
Android/README.md
View 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
@ -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`.

8
Doc/includes/wasm-ios-notavail.rst
View File

@ -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.

6
Doc/includes/wasm-mobile-notavail.rst Normal file
View File

@ -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>`.

2
Doc/library/curses.rst
View 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::

8
Doc/library/dbm.rst
View 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

2
Doc/library/ensurepip.rst
View 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
----------------------

2
Doc/library/grp.rst
View 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

72
Doc/library/intro.rst
View 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.
there are several major differences:
* 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.
* 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`.
* 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.
* Subprocesses:
* iOS apps have limited access to modify system resources (such as the system
* 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:
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``.
* 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.
As a result, Python library that involve console manipulation (such as
:mod:`curses` and :mod:`readline`) are not available on iOS.
* 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``.
* 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 modules that involve console manipulation (such as
:mod:`curses` and :mod:`readline`) are not available on mobile platforms.

2
Doc/library/multiprocessing.rst
View File

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

86
Doc/library/os.rst
View 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.
@ -549,7 +549,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
@ -585,21 +585,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, /)
@ -693,14 +693,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
@ -709,7 +709,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
@ -718,7 +718,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, /)
@ -741,7 +741,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
@ -2208,7 +2208,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`.
@ -4314,7 +4314,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
@ -4517,7 +4517,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()
@ -4544,7 +4544,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, /)
@ -4653,7 +4653,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
@ -4765,7 +4765,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=(), \
@ -4781,7 +4781,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.
@ -4814,7 +4814,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
@ -4883,7 +4883,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
@ -5011,7 +5011,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()
@ -5055,7 +5055,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::
@ -5089,7 +5089,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
@ -5130,7 +5130,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
@ -5150,7 +5150,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)
@ -5164,7 +5164,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
@ -5181,7 +5181,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.
@ -5196,7 +5196,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
@ -5207,7 +5207,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
@ -5219,7 +5219,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
@ -5232,7 +5232,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
@ -5241,7 +5241,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
@ -5251,7 +5251,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
@ -5264,7 +5264,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
@ -5299,7 +5299,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
@ -5315,7 +5315,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)
@ -5326,7 +5326,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)
@ -5338,14 +5338,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)
@ -5354,7 +5354,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)
@ -5363,7 +5363,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)
@ -5372,7 +5372,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)
@ -5381,7 +5381,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

2
Doc/library/readline.rst
View 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::

2
Doc/library/socket.rst
View File

@ -1280,7 +1280,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

2
Doc/library/subprocess.rst
View 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
----------------------------------

4
Doc/library/time.rst
View 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

2
Doc/library/venv.rst
View 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
-----------------------------

2
Doc/library/webbrowser.rst
View 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:

65
Doc/using/android.rst Normal file
View File

@ -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.

2
Doc/using/index.rst
View 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

2
Doc/using/ios.rst
View 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

14
Doc/whatsnew/3.13.rst
View 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.
@ -489,8 +490,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`.)
@ -2517,6 +2520,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`.)

1
Misc/ACKS
View File

@ -1745,6 +1745,7 @@ Christopher Smith
Eric V. Smith
Ethan H. Smith
Gregory P. Smith
Malcolm Smith
Mark Smith
Nathaniel J. Smith
Roy Smith

1
Misc/NEWS.d/next/Documentation/2024-09-19-19-33-25.gh-issue-116622.M65UZ6.rst Normal file
View File

@ -0,0 +1 @@
Add an Android platform guide, and flag modules not available on Android.