Skip to content

gh-116622: Complete Android documentation #124259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Sep 23, 2024
Merged

gh-116622: Complete Android documentation #124259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
8015ef4
Add Android to docs of unsupported features it shares with iOS
mhsmith Sep 19, 2024
2e08c09
Add additional markers for unsupported features on Android
mhsmith Sep 19, 2024
0f8c9da
Clarify emulator RAM size instructions
mhsmith Sep 19, 2024
879c805
Add Android platform guide
mhsmith Sep 19, 2024
98d7216
Update whatsnew and ACKS
mhsmith Sep 19, 2024
2c6ec29
Various fixes
mhsmith Sep 19, 2024
35384ab
Updates from code review.
freakboy3742 Sep 23, 2024
023598c
Correct markup
freakboy3742 Sep 23, 2024
9803d40
Merge branch 'main' into android-docs
freakboy3742 Sep 23, 2024
a5190e5
List more recommended Android tools
mhsmith Sep 23, 2024
e241163
Merge branch 'main' into android-docs
Yhg1s Sep 23, 2024
99e4c12
Apply suggestions from code review
mhsmith Sep 23, 2024
eabbf45
Improve formatting
mhsmith Sep 23, 2024
7fd73d1
Use consistent order in wasm-mobile-notavail.rst
mhsmith Sep 23, 2024
33efbf0
List Android under "Build Changes" in whatsnew
mhsmith Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 12 additions & 11 deletions Android/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 changes: 0 additions & 8 deletions Doc/includes/wasm-ios-notavail.rst
View file
Open in desktop

This file was deleted.

6 changes: 6 additions & 0 deletions Doc/includes/wasm-mobile-notavail.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 changes: 1 addition & 1 deletion Doc/library/curses.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand Down
8 changes: 6 additions & 2 deletions Doc/library/dbm.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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

Comment on lines +210 to +211
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.. include:: ../includes/wasm-mobile-notavail.rst

.. exception:: error

Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is
Expand Down Expand Up @@ -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

Comment on lines +331 to +332
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.. include:: ../includes/wasm-mobile-notavail.rst

.. exception:: error

Raised on :mod:`dbm.ndbm`-specific errors, such as I/O errors. :exc:`KeyError` is raised
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/ensurepip.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------------------
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/grp.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
78 changes: 46 additions & 32 deletions Doc/library/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
2 changes: 1 addition & 1 deletion Doc/library/multiprocessing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

--------------

.. include:: ../includes/wasm-ios-notavail.rst
.. include:: ../includes/wasm-mobile-notavail.rst

Introduction
------------
Expand Down
Loading
Loading