mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

[3.13] gh-116622: Complete Android documentation (GH-124259) (#124395)

Browse source 
gh-116622: Complete Android documentation (GH-124259)
(cherry picked from commit e80dd3035f)

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>
This commit is contained in:
Miss Islington (bot) 2024-09-24 02:13:45 +02:00 • committed by GitHub
parent afeb7a4ff5
commit 9a60a9ddaf
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 202 additions and 108 deletions
Download patch file Download diff file Expand all files Collapse all files

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

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

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

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: