Using Pythonista

This page provides an overview of Pythonista’s user interface, and also contains some useful tips and tricks to help you get the most out of it.

The Script Library

Pythonista is divided into three panels: The script library, the code editor, and the interactive prompt, which also contains the documentation viewer. You can switch between these panels with left and right swipe gestures.

The script library shows all the scripts you’ve written and those that are included as examples. You can either view them as a list of file names, or as code snippet previews. The view mode can be changed in the settings.

To create a new script, tap the + button at the bottom of the file browser. This will open the template picker to select the type of file, and its name.

To delete scripts, or move them to a different folder, tap the Edit button first.

The script library also shows non-Python files, e.g. data files that your scripts create or work with. For many file types, a preview can be shown, and you can also open them in a different app on your device.

The Interactive Prompt

The interactive prompt is the easiest way to get started with Python. Every time you enter a line of code, it is executed immediately, so you get quick feedback and can experiment with the syntax. Even if you know (almost) nothing about Python, you’ll be able to use the prompt as a powerful calculator.

You can get to the prompt at any time by doing a left swipe gesture. This area is also used for text output of any scripts that you run and for keyboard input (e.g. when you use the raw_input() function).

When you enter code, completions are suggested automatically.

The console’s output area can also show images, e.g. when using the PIL (Python Imaging Library) module, or matplotlib.

Tip

The Pythonista-specific console module allows you to modify the console’s output font, colors, and to clear the text output programmatically.

The Editor

If you’ve used any programming editor before, you’ll probably feel right at home in Pythonista. For the most part, the editor behaves very similar to any other text area on iOS, but there are some additional features that might not be obvious at first.

First off, the keyboard contains additional keys with special characters that are useful for programming. These additional keys also work as a gesture area: You can slide across them with your finger to move the cursor, which makes it easier to position it precisely.

For navigating in complex scripts, you can tap the name of the script at the top of the screen, to get a popup of all functions, classes, and methods. This is also where you can rename a file.

When you use the scene, ui or sound modules, you can insert names of built-in images, sound effects, and colors using the [+] button at the top.

One very powerful feature of the editor is that it is programmable itself. You can use the editor module for replacing text, positioning the cursor, etc. You can then add your own scripts to the action (“wrench”) menu, so that you can run them directly from the editor when working on your code.

Tap the Edit button in the actions panel to add your own scripts.

Have a look at the documentation about the editor module for some interesting examples.

..tip::

Tap with two fingers to select an entire line.

Using External Keyboards

You can connect a Bluetooth keyboards to your iOS device from the system preferences. Pythonista supports all the common keyboard shortcuts for text editing, and a few additional ones.

Common keyboard shortcuts (these work in all text areas on iOS):

• Command + X – Cut
• Command + C – Copy
• Command + V – Paste
• Command + Z – Undo
• Command + Shift + Z – Redo
• Command + A – Select All

Pythonista keyboard shortcuts:

• Command + R – Run
• Command + F – Toggle search
• Command + G – Show next search result
• Command + Shift + G – Show previous search result
• Command + K – Clear console output

Please note that most of these shortcuts only work when a text area has keyboard focus.

The Pythonista App Extension

Pythonista includes an app extension that allows you to run Python scripts from within other apps. The extension is invoked from the iOS share sheet that is available in many apps.

Before using the extension for the first time, you need to enable it. To do this, tap the “More” button at the bottom of the share sheet, then turn on the switch for “Run Pythonista Script”.

The extension contains an editable collection of shortcut icons (similar to the “wrench” menu in the editor) to run your favorite scripts quickly, but there’s also a basic code editor, and an interactive console to enable tweaking your code directly in the extension. Apps that support the share sheet typically pass some kind of data to it, e.g. the current page’s URL in Safari, text in Notes, location data in Maps, or images in Photos. You can use the appex module to access this data.

The Pythonista URL Scheme

Pythonista can be launched from other apps using the pythonista://... URL scheme. For more information and a reference of the parameters you can pass, please read the chapter The Pythonista URL Scheme.

Settings

You can access the settings by tapping the gear icon in the file browser.

General Settings

• Theme: You can choose from multiple light and dark themes for syntax highlighting and UI colors.
• Code Font: The typeface and font size that is used in the code editor.
• Extended Keyboard with Numbers: When enabled, an additional row of extra keys is shown above the keyboard (iPad only).

Script Library Settings

• Thumbnail Previews: When enabled, the script library shows larger preview images for files instead of a list of file names.
• Sort by: Files in the script library can be sorted by name or date.
• Show Standard Library: When enabled, the standard library and included third-party modules can be viewed in the editor. Note that these files are always read-only.

Editor Settings

• Indentation: You can configure the width of tab characters in the editor, and whether to use spaces (“soft tabs”) for indentation. Note that the built-in examples are written with “hard” tabs, so if you want to edit them, it’s recommended that you either leave “soft tabs” off, or that you use the built-in “Convert Indentation...” action before editing. The Show Mixed Indentation setting makes the other sort of indentation characters visible in the editor, i.e. if you use soft tabs, tab characters are made visible.
• Automatic Character Pairs: Controls whether the closing part of paired characters, like parentheses or brackets, is inserted automatically

Console Settings

• Clear Output Before Running: When enabled, the previous console output is cleared automatically before running a script.
• Use “True” Division: When enabled, the interactive console always uses “true” division, i.e. 1/2 is evaluated as 0.5 instead of 0 (which would be the default behavior in Python 2.7). Note that this setting does not apply to scripts that you run from the editor. For that, you can just use from __future__ import division.