Python iOS Template

A template for building Python apps that will run under iOS.

This repository branch contains a template for Python 3.6. Other Python versions are available by cloning other branches of repository.

Using this template

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 your setup.py.

However, if you do want use this template directly...

1. Install cookiecutter. This is a tool used to bootstrap complex project templates:

   $ pip install cookiecutter
   

2. Run cookiecutter on the Python-iOS template:

   $ cookiecutter https://github.com/pybee/Python-iOS-template --checkout 3.6
   

3. Download the Python Apple support package for iOS, and extract it. This will create a support directory containing four libraries:

   • BZip2
   • OpenSSL
   • XZ
   • Python

   Alternatively, you can download the Python-Apple-support project, and build your own versions of these frameworks.

   These framework directories should be placed in the same directory as the app and app_packages directories generated by the cookiecutter project template.

4. Add your code to the template. At the very minimum, you need to have an app/<app name>/app.py file that defines a PythonAppDelegate class. If <app name> contains a dash, it will be converted to an underscore in the expected package name

   If your code has any dependencies, they should be installed under the 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:

iOS/
    app/
        my-project/
            __init__.py
            app.py (declares PythonAppDelegate)
    app_packages/
        ...
    myproject/
        ...
    My Project.xcodeproj/
        ...
    support/
        ...

You're now ready to open the XCode project file, build and run your project!

Next steps

Of course, just running Python code isn't very interesting by itself - you'll be able to output to the console, and see that output in XCode, but if you tap the app icon on your phone, you won't see anything - because there isn't a visible console on an iPhone.

To do something interesting, you'll need to work with the native iOS system libraries to draw widgets and respond to screen taps. The Rubicon Objective C bridging library can be used to enable an easy interface with the iOS system libraries. You could also use the toga library to provides a cross-platform widget toolkit that supports iOS.

Regardless of whether you use Toga, or you write an application natively, the template project will try to instantiate a UIApplicationMain instance, using a class named PythonAppDelegate as the App delegate. If a class of that name can't be instantiated, the error raised 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.

It's also worth noting that the app and app_packages code don't need to contain the actual code. If it's more convenient to keep the code somewhere else, you can symlink to the actual code inside the app or app_packages directory. At compile time, the symlink will be resolved and copied to the app bundle, but during development, you can avoid having copies of code in your source repositories.

One pattern for doing this is to have a top level project directory that contains the source module, and an iOS directory at the same level that links in the project source:

myproject/
    iOS/
       app/
           myproject -> ../../myproject
       ...
    myproject/
        __init__.py
        main.py
        other.py
    setup.py