The Pythonista URL Scheme#

Pythonista can be launched from other applications with the custom pythonista:// URL scheme.

Tip

You can generate pythonista3:// URLs easily using the integrated URL and QR code generator. Tap on the “wrench” icon while editing a script, and select “Shortcuts” to get started. See also: App Extensions and Shortcuts.

Basics#

  • Open the app:

    Use pythonista:// without any additional parameters to open the app without doing anything else.

  • Open a script for editing:

    Use pythonista://MyScript.py for opening one of your scripts in the editor. By default, the script path is relative to Pythonista’s local documents folder. Add ?root=icloud or use a path like iCloud/MyScript.py to make the path relative to Pythonista’s iCloud folder instead.

  • Run a script from your library:

    Use pythonista://MyScript.py?action=run for running a script that is in your library. By default, the script path is relative to Pythonista’s local documents folder. Add ?root=icloud to make the path relative to Pythonista’s iCloud folder instead.

  • Execute a snippet of Python code:

    Use pythonista://?exec=<your code> to run code that is embedded directly in the URL. Note that the code is always shown to the user for confirmation before actually executing it.

    In Pythonista 3.x, you can specify whether the code should be run with Python 3 or Python 2.7 by including a “shebang” as the first line (e.g. #! python2 or #! python3).

Note

In Pythonista 3.x, you can use pythonista3:// instead of pythonista://. In Pythonista 2 (starting with 2.1), you can use pythonista2://. Use these schemes if you want to target a specific version of the app. In case both apps are installed, it is undefined which one of them handles a pythonista:// URL.

Command-line Arguments#

When using the action=run parameter (see above), you can pass command-line arguments to the script in two ways:

  • Method 1: One args parameter

    Example: pythonista://MyScript?action=run&args=foo%20bar

    When you pass a single string with the args URL parameter, the string is split by spaces (the space is encoded as %20 here) and sys.argv would be [<script_path>, 'foo', 'bar'] in this example.

    If you want to pass arguments that contain spaces, you have to enclose them in double quotes (as you would in a classic shell).

    This is basically the same as running a script by long-pressing the run button.

  • Method 2: Multiple argv parameters

    Example: pythonista://MyScript?action=run&argv=foo&argv=bar

    Using multiple arguments that are all named argv, you don’t have to worry about quoting arguments that contain spaces. Each of the parameters corresponds to one element in sys.argv.

    If the URL contains at least one argv parameter, args is ignored.

Launching Other Apps#

If you want to go in the opposite direction, and open an app from Pythonista, you can do this with the webbrowser or the shortcuts module.

For example, to open the Twitter app, you could use the following code:

import webbrowser
webbrowser.open('twitter://')

or:

import shortcuts
shortcuts.open_url('twitter://')