Debian Codegraph @

Doc/using/android.rst

raw
1 .. _using-android:
2
3 =======================
4 Using Python on Android
5 =======================
6
7 Python on Android is unlike Python on desktop platforms. On a desktop platform,
8 Python is generally installed as a system resource that can be used by any user
9 of that computer. Users then interact with Python by running a :program:`python`
10 executable and entering commands at an interactive prompt, or by running a
11 Python script.
12
13 On Android, there is no concept of installing as a system resource. The only unit
14 of software distribution is an "app". There is also no console where you could
15 run a :program:`python` executable, or interact with a Python REPL.
16
17 As a result, the only way you can use Python on Android is in embedded mode – that
18 is, by writing a native Android application, embedding a Python interpreter
19 using ``libpython``, and invoking Python code using the :ref:`Python embedding
20 API <embedding>`. The full Python interpreter, the standard library, and all
21 your Python code is then packaged into your app for its own private use.
22
23 The Python standard library has some notable omissions and restrictions on
24 Android. See the :ref:`API availability guide <mobile-availability>` for
25 details.
26
27 Adding Python to an Android app
28 -------------------------------
29
30 Most app developers should use one of the following tools, which will provide a
31 much easier experience:
32
33 * `Briefcase <https://briefcase.beeware.org>`__, from the BeeWare project
34 * `Buildozer <https://buildozer.readthedocs.io>`__, from the Kivy project
35 * `Chaquopy <https://chaquo.com/chaquopy>`__
36 * `pyqtdeploy <https://www.riverbankcomputing.com/static/Docs/pyqtdeploy/>`__
37 * `Termux <https://termux.dev/en/>`__
38
39 If you're sure you want to do all of this manually, read on. You can use the
40 :source:`testbed app <Android/testbed>` as a guide; each step below contains a
41 link to the relevant file.
42
43 * First, acquire a build of Python for Android:
44
45 * The easiest way is to download an Android release from `python.org
46 <https://www.python.org/downloads/android/>`__. The ``prefix`` directory
47 mentioned below is at the top level of the package.
48
49 * Or if you want to build it yourself, follow the instructions in
50 :source:`Android/README.md`. The ``prefix`` directory will be created under
51 :samp:`cross-build/{HOST}`.
52
53 * Add code to your :source:`build.gradle <Android/testbed/app/build.gradle.kts>`
54 file to copy the following items into your project. All except your own Python
55 code can be copied from ``prefix/lib``:
56
57 * In your JNI libraries:
58
59 * ``libpython*.*.so``
60 * ``lib*_python.so`` (external libraries such as OpenSSL)
61
62 * In your assets:
63
64 * ``python*.*`` (the Python standard library)
65 * ``python*.*/site-packages`` (your own Python code)
66
67 * Add code to your app to :source:`extract the assets to the filesystem
68 <Android/testbed/app/src/main/java/org/python/testbed/MainActivity.kt>`.
69
70 * Add code to your app to :source:`start Python in embedded mode
71 <Android/testbed/app/src/main/c/main_activity.c>`. This will need to be C code
72 called via JNI.
73
74 Building a Python package for Android
75 -------------------------------------
76
77 Python packages can be built for Android as wheels and released on PyPI. The
78 recommended tool for doing this is `cibuildwheel
79 <https://cibuildwheel.pypa.io/en/stable/platforms/#android>`__, which automates
80 all the details of setting up a cross-compilation environment, building the
81 wheel, and testing it on an emulator.