Android¶

Chaquopy is distributed as a plugin for Android’s Gradle-based build system. For a full example of how to use it, see the demo app.

Prerequisites:

Android Gradle plugin version 2.2, 2.3 or 3.0. (This is specified as com.android.tools.build:gradle in your project’s top-level build.gradle file, and will usually be the same as your Android Studio version.)
minSdkVersion 15 or higher.

Basic setup¶

Plugin¶

In the project’s top-level build.gradle file, add the Chaquopy repository and dependency to the end of the existing repositories and dependencies blocks:

buildscript {
    repositories {
        ...
        maven { url "https://chaquo.com/maven" }
    }
    dependencies {
        ...
        classpath "com.chaquo.python:gradle:1.1.0"
    }
}

In the app’s module-level build.gradle file, apply the Chaquopy plugin at the top of the file, but after the Android plugin:

apply plugin: "com.chaquo.python"    // Must come after com.android.application

Python version¶

With the plugin applied, you can now add a python block within android.defaultConfig. The only required setting in this block is the Python version, and the currently available versions are:

2.7.10
3.6.3

For example:

defaultConfig {
    python {
        version "2.7.10"
    }
}

ABI selection¶

The Python interpreter is a native component, so you must specify which native ABIs you want the app to support. The currently available ABIs are:

armeabi-v7a, for the vast majority of Android hardware.
x86, for the Android emulator.

During development you will probably want to enable them both:

defaultConfig {
    ndk {
       abiFilters "armeabi-v7a", "x86"
    }
}

There’s no need to actually install the Android native development kit (NDK), as Chaquopy will download pre-compiled CPython binaries for the selected ABIs.

Note

Each ABI will add several MB to the size of the app. Because some of the native components are stored as assets, the split APK feature cannot be used to mitigate this. If you want to build separate APKs for each ABI, this can instead be done using a product flavor dimension:

android {
    flavorDimensions "abi"
    productFlavors {
        armeabi_v7a {
            dimension "abi"
            ndk { abiFilters "armeabi-v7a" }
        }
        x86 {
            dimension "abi"
            ndk { abiFilters "x86" }
        }
    }
}

Development¶

Place Python source code in src/main/python, and Chaquopy will automatically build it into the app.

It’s important to structure the app so that Python.start() is always called with an AndroidPlatform before attempting to run Python code. There are two basic ways to achieve this:

If the app always uses Python, then call Python.start() from a location which is guaranteed to run exactly once per process. The recommended location is Application.onCreate(), and a PyApplication subclass is provided to make this easy. To use it, simply add the following attribute to the <application> element in AndroidManifest.xml:
```
android:name="com.chaquo.python.android.PyApplication"
```

Alternatively, if the app only sometimes uses Python, then call Python.start() after first checking whether it’s already been started:

// "context" must be an Activity, Service or Application object from your app.
if (! Python.isStarted()) {
    Python.start(new AndroidPlatform(context));
}

Other build features¶

These features all require a Python interpreter (version 2.7 or 3.3+) to be available on the build machine. Chaquopy will by default look for python on your PATH, but this can be configured with the buildPython setting. For example, a typical Windows installation of Python would look like this:

python {
    buildPython "C:/Python27/python.exe"
}

Python requirements¶

External Python packages may be built into the app by adding a python.pip block to build.gradle. Within this block, add install lines, each specifing a package in one of the following forms:

A pip requirement specifier.
A local wheel filename (relative to the project directory).
"-r" followed by a local requirements filename (relative to the project directory).

Examples:

python {
    pip {
        install "six==1.10.0"
        install "LocalPackage-1.2.3-py2.py3-none-any.whl"
        install "-r", "requirements.txt"
    }
}

Note

Chaquopy can only install wheel files, not sdist packages. As well as PyPI, Chaquopy also searches for wheels in its own package repository, which contains Android builds of certain native packages, as well as pure-Python packages which aren’t available from PyPI in wheel format.

To see which packages and versions are currently available, you can browse the repository here. To request a package to be added or updated, please visit our issue tracker.

To pass options to pip install, give them as a comma-separated list to the options property. For example:

python {
    pip {
        options "--extra-index-url", "https://example.com/private/repository"
        install "PrivatePackage==1.2.3"
    }
}

There may be multiple options lines: the options will be combined in the order given. Any pip install options may be used, except the following:

Target environment options, such as --target and --user.
Installation format options, such as -e and --egg.
Package type options, such as --no-binary.

Static proxy generator¶

In order for a Python class to extend a Java class, or to be referenced by name in Java code or in AndroidManifest.xml, a Java proxy class must be generated for it. The staticProxy setting specifies which Python modules to search for these classes:

python {
    staticProxy "module.one", "module.two"
}

The app’s source tree and its requirements will be searched, in that order, for the specified modules. Either simple modules (e.g. module/one.py) or packages (e.g. module/one/__init__.py) may be found.

Within the modules, static proxy classes must be declared using the syntax described in the static proxy section. For all declarations found, Java proxy classes will be generated and built into the app.

Licensing¶

Evaluation¶

You can try out Chaquopy right now by cloning one of the example apps, or following the setup instructions above in an app of your own. The unlicensed version is fully-functional, but apps built with it will display a notification on startup.

In order to distribute apps built with Chaquopy, a license is required. All licenses are perpetual and include upgrades to all future versions.

Commercial license¶

A commercial license allows unlimited use of Chaquopy by a single developer. While Chaquopy is in beta, licenses are available free of charge. Please contact us to obtain a license key.

Once you have a key, add the following line to the project’s local.properties file:

chaquopy.license=<license key>

Open-source license¶

If your app is open-source, you may obtain a license for it free of charge. Please contact us with details of your app, including:

The app ID (package name)
Where the app is distributed (e.g. Google Play)
Where the app’s source code is available

Once the app ID is activated on our server, anyone will be able to use Chaquopy to build the app by adding the following line to the project’s local.properties file:

chaquopy.license=