App Extensions and Shortcuts#
This page provides an overview of the different areas where Pythonista scripts can be utilized to enhance iOS, other applications, and Pythonista itself.
To access most of these features, tap the “wrench” icon in the editor and choose “Shortcuts”.
Siri and Shortcuts App#
The Shortcuts app lets you build workflows (“shortcuts”), consisting of one or more actions, which are comparable to lines of code or function calls, but typically do a lot more at once than a typical line of Python would.
Actions are composed by drag’n’drop instead of writing code, and while this leads to quick results without any coding, it can often be somewhat tedious to express complex logic using this building block approach.
This is where Pythonista comes in. When the app is installed, additional actions for running Python scripts automatically become available in the Shortcuts app, which allow you to express more complex logic (or things not covered by the built-in actions) using Python scripts.
While there are certain limitations for background scripts running in Shortcuts (limited memory/runtime, no interactive UI), this lets you use Python for all the things that can be automated on iOS through Shortcuts, e.g. triggering a script when you arrive at a location, get a message from a particular person, open a specific app, and much more.
How to Use
You create shortcuts with the Shortcuts app, which comes pre-installed on iOS/iPadOS. Once Pythonista is installed, additional actions become available in the Shortcuts app, most notably the “Run Pythonista Script” action, allowing you to run a Python script within a shortcut.
Shortcuts can be applied in numerous locations on iOS. You can set up a shortcut to execute every time you launch a specific app or reach a location, you can activate shortcuts from widgets, Siri, and more. For comprehensive information about everything you can do with the Shortcuts app, please see Apple’s Shortcuts Documentation.
More detailed information about Pythonista’s custom Shortcuts actions is available in the shortcuts module documentation.
More Information
shortcutsmodule – Information about Pythonista’s custom actions and functions for input/output of scripts running in ShortcutsLaunch Shortcuts App <shortcuts://>`_
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
keyboardmodule 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
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
appexmodule, 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(withappex.get_image()) orui(withappex.get_ui_image()). WhilePILis cross-platform, theuimodule 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
editormodule.
More Information
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
Home Screen Icon#
Previous versions of Pythonista allowed to create homescreen icon shortcuts for individual scripts directly from the app. This worked through custom Safari bookmarks, which redirected to the main Pythonista app, which would then run the script.
Since the Shortcuts app has been a part of iOS, it provides a much better experience for adding home screen shortcuts, and as those shortcuts can also contain Pythonista scripts, the previous “add to home screen” feature has been removed from Pythonista itself.
To add a shortcut to the home screen:
In the Shortcuts app, tap (…) on a shortcut, then tap (i) to open Details.
Tap Add to Home Screen
You can also set a custom icon for the home screen shortcut.
Pythonista URLs#
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
webbrowsermoduleshortcutsmodule