shortcuts — Shortcuts Automation and URL Scheme Utilities#

Introduction#

The shortcuts module provides functions for integrating with the built-in Shortcuts app (and Siri) on iOS 13 and later, plus some utilities for URL scheme automation on any version of iOS.

The Shortcuts app lets you build shortcuts (previously known as “workflows”) out of one or more actions. Building shortcuts is very much like programming, though you typically don’t write any code, and a shortcut’s actions do a lot more at once than a typical function call in a programming language like Python. While this leads to much quicker results, there is sometimes a compromise between ease of use and flexibility. Fortunately, third-party apps like Pythonista can extend the Shortcuts app with their own sets of actions that you can use to automate a growing list of apps through the use of Shortcuts, and increasingly complex use cases are possible.

Pythonista provides a couple of Shortcuts actions that automatically become available in the Shortcuts app when Pythonista is installed.

Pythonista Actions in Shortcuts#

Run Pythonista Script#

Run Pythonista Script Action in Shortcuts

This is the action that you’ll probably use most with Pythonista. It allows you to run a Python script, either by launching the Pythonista app (and optionally returning to Shortcuts afterwards), or by running the script directly in the Shortcuts app, passing the results to the next action and/or presenting them within the Shortcuts UI.

By default, you can choose a script from your Pythonista library to run when the action executes. By using the “Inline Script” option, however, you can also type in a snippet of Python code directly in the Shortcuts app.

Both library and inline scripts can run in the main Pythonista app or directly in Shortcuts (depending on whether the “Run in Pythonista” option is on). There are a couple of differences between these two run modes, and you might want to use one or the other, depending on the script you’re running. In general, scripts running in Shortcuts have much more limited memory resources and cannot show a user interface, apart from presenting results after the script has run. On the plus side though, they don’t launch the Pythonista app at all, and they can pass their output directly to the next action in the shortcut, so you might often prefer this way of running scripts for shortcuts consisting of many actions.

When “Run in Pythonista” is on, an additional “Auto-Return to Shortcuts” option appears. When this is on, Pythonista will automatically return to the Shortcuts app when the script has finished running. You might want to disable it if your script handles returning to Shortcuts itself (e.g. by calling shortcuts.open_shortcuts_app() at some point).

The “Show When Run” option determines whether the action’s output will be shown in the Shortcuts app after the script has run. This only has an effect when “Run in Pythonista” is off. When you turn this off, the action will still pass output to the next action in the workflow, but no UI will be shown.

Arguments and Input Files

There are two ways of passing input from other shortcut actions to your script. Both Arguments and Input Files are added to sys.argv, just like command-line arguments. The difference is that Arguments are converted to plain text (i.e. a string) and Input Files are written to a temporary disk location and passed as an absolute file path.

Output

First off, only scripts that run within Shortcuts (“Run in Pythonista” off) will directly produce output that other actions in the shortcut can use. You can work around this by writing output to a file, and using an additional “Get Pythonista File” action.

By default, the action’s output will be anything that would normally be printed to the console, i.e. you can simply use print() calls to pass text to other actions in the shortcut. Of course, you’re not limited to working with text, so you can use various functions in this module to generate output of other data types, like set_output_image(), set_output_data(), and set_output_files().

If “Show When Run” in on, the action will also present a “result sheet” to the user after the script has run. By default, this also shows console output, but you can customize this completely, using HTML/CSS.

Add File to Pythonista#

This action copies a file (produced by another action) to Pythonista’s script library, optionally overwriting an existing file with the same name.

Get Pythonista File#

This action reads a file from Pythonista’s script library, and passes its contents to the next action. The file name can include folders (e.g. “MyFolder/MyScript.py”). To reference files in Pythonista’s iCloud folder, prefix the path with “icloud/”, e.g. “icloud/MyScript.py”.

Run Script / Edit Script (deprecated)#

You might see these two actions for Pythonista in the Shortcuts app as well. While at the time of writing, they still work, it is not recommended that you use them for new shortcuts. These actions have been built into the Shortcuts app back from the days when it was called “Workflows” (and wasn’t part of Apple). Since it’s now possible for third-party apps like Pythonista to provide their own Shortcuts support, it is likely that these actions will disappear from the Shortcuts app at some point in the future.

Functions#

shortcuts.is_running_shortcut()#

Return True if the current script is running as a background shortcut, False otherwise (when running in the main app, or a different kind of app extension).

shortcuts.open_shortcuts_app(name=None, shortcut_input='')#

Open the Apple Shortcuts app and optionally run a named shortcut. Equivalent to shortcuts.open_url('shortcuts://run-shortcut?name=[name]&input=shortcut_input').

shortcuts.open_url(url)#

Open a given URL using the system’s default app for the URL’s scheme. This is mostly equivalent to webbrowser.open(). Note that you cannot open URLs in a script that is running as a background shortcut.

shortcuts.set_output_data(data, filename, uti=None)#

Set the output of the current shortcut action script. data should be a byte string, the data type is inferred from the filename argument, or given explicitly as a UTI.

shortcuts.set_output_image(image)#

Set the output of the current shortcut action script as an image (either a path to an image file as a string, a PIL.Image.Image, or a ui.Image object).

shortcuts.set_output_files(file_infos)#

Set the output of the current shortcut action script from a list of files.

file_infos should be list of dict objects with the following keys:

  • 'path' – An absolute path to an existing file.

  • 'data' – The contents of the file as a bytes object (for in-memory files)

  • 'filename' – The file’s name (for in-memory files without a path)

  • 'uti' – The file’s `Uniform Type Identifier <>`_ (optional)

shortcuts.set_result_html(html)#

Set HTML-formatted text to be shown as the result when running a background shortcut script in Siri or the Shortcuts app. The given html is inserted in a template that contains the document structure and some default formatting, so it can just be a snippet of markup.

The result is only shown when the “Show When Run” option is activated in the Shortcuts app.

If you just want to show some text or image in the result view, you can also just use print() or ui.Image.show() etc.

shortcuts.pythonista_url(path='', action='run', args=None, argv=None)#

Generates a pythonista3://... URL from a file name/path, an action, and optional arguments.

Possible values for action are:

  • 'run' – Opening the URL will run the script without further prompt.

  • 'open' – Opening the URL will open the script for editing.

  • 'exec' – The script will be embedded as source code in the URL, and opening the URL will show it in Pythonista. The user can then decide to run it (embedded scripts are not run automatically for security reasons).

The path should either be relative to the root “on this device” directory, or have an ‘iCloud/’ prefix, and be relative to the iCloud container directory of Pythonista.

args can be a string that contains arguments that are passed to the script as sys.argv. Alternatively, you can use the argv parameter to pass the arguments as a list.