A Cookiecutter template for building Python apps that will run under Android.
This repository branch contains a template for Python 3.11. Other Python versions are available by cloning other branches of repository.
The easiest way to use this project is to not use it at all - at least, not
directly. Briefcase is a tool that
uses this template, rolling it out using data extracted from a
pyproject.toml
configuration file.
However, if you do want use this template directly...
Install cookiecutter. This is a tool used to bootstrap complex project templates:
$ pip install cookiecutter
Run
cookiecutter
on the template:$ cookiecutter https://github.com/beeware/briefcase-android-gradle-template --checkout 3.11
This will ask you for a number of details of your application, including the name of your application (which should be a valid PyPI identifier), and the Formal Name of your application (the full name you use to describe your app). The remainder of these instructions will assume a name of
my-project
, and a formal name ofMy Project
.Download the Python support package for Android, and extract it into the
My Project
directory generated by the template. This will createapp/libs
andapp/src/main/assets
folders containing a self contained Python install.Alternatively, you can download the Python-Android-support project, and build your own version.
Add your code to the template, into the
My Project/app/src/main/assets/python/app
directory. At the very minimum, you need to have anMy Project/app/src/main/assets/python/app/<app name>/__main__.py
file that instantiates an instance oforg.beeware.android.IPythonApp
, and then invokesorg.beeware.android.MainActivity.setPythonApp()
, providing theIPythonApp
instance.If your code has any dependencies, they should be installed into the
My Project/app/src/main/assets/python/app_packages
directory.
If you've done this correctly, a project with a formal name of My Project
,
with an app name of my-project
should have a directory structure that
looks something like:
My Project/ app/ src/ main/ assets/ python/ app/ my_project/ __init__.py __main__.py (declares IPythonApp) app_packages/ ... cpp/ ... java/ ... res/ ... AndroidManifest.xml build.gradle proguard-rules.pro briefcase.toml build.gradle gradle.properties gradlew gradlew.bat settings.gradle
You're now ready to run build and run your project! Set
$ ./gradlew installDebug
Of course, running Python code isn't very interesting by itself - you'll be able to output to the console, and see that output in Gradle, but if you tap the app icon on your phone, you won't see anything - because there isn't a visible console on an Android.
To do something interesting, you'll need to work with the native Android system libraries to draw widgets and respond to screen taps. The Rubicon Java bridging library can be used to interface with the Android system libraries. Alternatively, you could use a cross-platform widget toolkit that supports Android (such as Toga) to provide a GUI for your application.
Regardless of whether you use Toga, or you write an application natively, the
template project will run the __main__ module associated with the app name
that you provided when you generated the tempalte. That Python code must
define an instance of org.beeware.android.IPythonApp
, and invoke
org.beeware.android.MainActivity.setPythonApp()
to set that instance as the
active Python app. This app will coordinate provides the hooks into the
Android application lifecycle (onCreate
, onResume
and so on); it's
up to you what your code does with those lifecycle hooks. If setPythonApp
is not set, an error will be logged, and the Python interpreter will be shut
down.
If you have any external library dependencies (like Toga, or anything other
third-party library), you should install the library code into the
app_packages
directory. This directory is the same as a site_packages
directory on a desktop Python install.