App Extensions and Shortcuts

This page gives you an overview of the various places where you can use Pythonista scripts to extend iOS, other apps, and Pythonista itself.

Most of these features are accessible by tapping the “wrench” button in the editor, and selecting “Shortcuts”.

• Pythonista Keyboard
• Share Extension
• Editor Action
• Home Screen Icon
• Pythonista URL

Pythonista Keyboard

The Pythonista keyboard is a custom on-screen keyboard that you can use in any app that has editable text. The keyboard includes a Python interpreter, so you can run scripts that manipulate text without ever launching the main Pythonista app. Scripts can insert text in the app, work with the selection, or even show completely custom user interfaces.

Please note that the Pythonista keyboard is not intended to replace the system keyboard for all your writing – it’s more like the Emoji keyboard, i.e. you’d typically switch to it briefly to run a script, and then switch back to the system keyboard (or any other custom keyboard) to do most of your typing. While the keyboard does include a standard QWERTY layout, there isn’t any kind of auto-correction or typing suggestions, so it’s not really suitable for long text input.

To give you an idea of what the keyboard is capable of, various scripts are included as examples.

How to Use

To start using the keyboard, tap and hold the “Globe” key on the system keyboard, and select “Keyboard Settings…”. From there, select “Keyboards > Add New Keyboard…”. You should find “Pythonista” in the list of available keyboard.

You may also want to enable the “Full Access” option after adding the keyboard, as some functionality won’t be available to your scripts otherwise (e.g. writing files that are readable by the main app or accessing the network). It’s generally possible to use the keyboard without full access enabled though.

After you’ve enabled the keyboard, you can switch to it anytime, using the “Globe” key. When you tap and hold the globe key, you can switch to any keyboard directly (without going through all of them by tapping).

In general, you can do most things you could do in a script that runs in the main app, but there are some limitations:

• Custom user interfaces run only within the keyboard, and cannot cover the entire screen. They’re also more limited in how views can be presented.
• Resources are more limited in general, and the keyboard may “crash”, if your scripts use too much memory (even if the scripts may run fine in the main app).

Tips:

• Tap and hold a script shortcut to edit the script or remove the shortcut.
• Tap the green key to expand the row of script shortcuts to the entire keyboard. This also expands any user interfaces that are shown in that view.
• Tap and hold the globe key to switch to a different keyboard directly, without going through all other keyboards.
• The keyboard module contains functions for dealing with text input and the keyboard in general. You can use this to insert text, move the cursor, get selected text, and more.
• The Python standard library contains a lot of modules for working with and transforming text, which may be interesting when used in a custom keyboard. Have a look at the Text Processing Services page to get an overview.
• Have a look at the included sample scripts to get an idea of what’s possible with a scriptable keyboard

More Information

• keyboard module
• ui module

Share Sheet Extension

The Pythonista share sheet extension allows you to run scripts from other apps that support the standard iOS share sheet, e.g. Safari, Photos, Notes, but also third-party apps (including Pythonista itself).

Your scripts have access to the share sheet’s input, e.g. a URL in Safari, or an image in Photos.

How to Use

To enable the Pythonista share sheet extension, simply share something in a supported app, e.g. Safari or Pythonista itself. Scroll down in the list of actions (or sideways on iOS 12 and earlier) to find the “Run Pythonista Script” action. If it’s not in the list already, tap on “More...” (on iOS 12) or “Edit Actions…” (on iOS 13+).

Scripting Tips for the Share Sheet

• You can access the share sheet’s input using various functions in the appex module, e.g. appex.get_url() to get a URL (e.g. in Safari), appex.get_text() to get text in e.g. Notes, appex.get_image() to get a shared photo, and more.
• You can dismiss the share sheet programmatically using the appex.finish() function.
• The share sheet extension contains an interactive prompt (console), so you can also work with the input data interactively, without writing a full script.
• If you want to process images in the share sheet extension, you can either use PIL (with appex.get_image()) or ui (with appex.get_ui_image()). While PIL is cross-platform, the ui module provides higher-quality vector drawing, and is generally a bit more light-weight.
• As in all app extensions, resources are more limited than in the main app (which makes “crashes” due to memory limitations more likely), and the share sheet extension runs in a separate process. Some modules are only supported in the main app, e.g. the editor module.

More Information

• appex module
• clipboard module
• ui module
• PIL module

Editor Action

Editor actions allow you to extend the popup that appears when you tap the “wrench” button, so you can run scripts while editing code or viewing other files.

Each editor action can have a custom icon/color, and you can create multiple actions from the same script by passing command-line arguments.

Editor actions are particularly useful for scripts that make use of the editor module (for scripting the text editor), but they can be anything that you want quick access to.

The “Reset Environment” option determines whether global variables etc. are deleted before the script is run. Normally, the runtime environment is reset before running a script, but if the editor action is related to debugging, it may be useful to keep the variables from the last script that was run.

More Information

• editor module
• dialogs module

Home Screen Icon

This allows you to add a custom home screen icon to launch a Pythonista script. Technically, these home screen icons are just Safari bookmarks, but they do work offline.

On iOS 13 and later, you may want to use a home screen shortcut from the Shortcuts app instead. You can launch Pythonista from the Shortcuts app by opening a pythonista:// URL (see below).

Pythonista URL

The Pythonista URL generator allows you to easily generate pythonista3:// URLs for launching or opening your scripts from other apps. You can also generate QR codes with embedded URLs that can be scanned by the iOS camera app.

Pythonista’s URL scheme support allows various kinds of automation, including launching scripts from the Shortcuts app or third-party automation tools.

For more information on what you can do with Pythonista URLs, please refer to the Pythonista URL Scheme reference.

You can also generate Pythonista URLs programmatically, using the shortcuts module.

More Information

• webbrowser module
• shortcuts module
• The Pythonista URL Scheme