Using the Shell in PythonCard
PythonCard integrates a rich, high-level interactive Python shell. This document describes how to launch and use this shell as you create PythonCard applications. It is based on Version 0.8.2 of PythonCard.
The PythonCard shell utilizes the PyCrust package created by Patrick O'Brien of Orbtech which is included with wxPython.
Overview of Basic Shell Functionality
In many ways, the PythonCard shell resembles the shell in IDLE, the Python editor that is included in Python distributions. IDLE is Python's default editor. But the PythonCard shell is more extensive and more robust both in its editing capabilities and in its programming support than IDLE.
As you can see from Figure 1, the shell allows you to do interactive programming at the standard Python prompt of three angle brackets (">>>"). It behaves like IDLE, so there's nothing new to learn in this respect.
Figure 1. Using PythonCard Shell as Interactive Programming Environment
Figure 1 also illustrates the shell's inclusion of syntax highlighting and coloring, which can be customized via the codeEditor Styles dialog.
Pressing Enter anywhere on a line in the shell always processes the command on that line if that line is the last one in the current editing window. Pressing Enter on any other line copies that line's contents and places them on the last line in the window, enabling you to execute the command again or modify it slightly. This feature is quite valuable during testing when you often type the same commands repeatedly. In Figure 2, we positioned the cursor at the end of the line containing the simple statement "5+2" and pressed Enter. Notice that 5+2 now appears as the last line in the editor. Pressing Enter now produces the expected output of "7" on the next line in the editor.
Figure 2. Copying a Previous Command Line With Enter Key
You can use the ESCape key to change your mind about a line of Python code you are entering that has not yet been executed bypressing Enter. This will simply erase all the characters on the current line and return your cursor to the Python prompt.
You can always obtain some basic help in the use of the shell by typing "shell.help()" in the interactive editor area and pressing Enter. The result will look something like Figure 3.
Figure 3. Result of Typing "shell.help()" in PythonCard Shell
The arrow keys navigate up, down, left and right in text displayed in the shell, as you'd expect. Holding down the Ctrl key with the right or left arrow moves the cursor by the rough equivalent of a "word" in the direction of the arrow, with movement continuing across line boundaries.
By default, lines typed into the shell wrap. If you don't wish to see the lines in your shell window wrap at the right border of the shell window, type in the shell: shell.SetWrapMode(0). To turn it back on, type shell.SetWrapMode(1).
Key Bindings in the Shell
Table 1 shows all of the key bindings defined in the PythonCard shell and describes their usage.
Table 1. Key Bindings in PythonCard Shell
| Key Combination | Usage |
|---|---|
| Home | Go to the beginning of the line |
| Shift + Home | Select from current cursor position to the beginning of the line |
| Shift + End | Select from the current cursor position to the end of the line |
| End | Go to the end of the line |
| Ctrl + Right Arrow | Move cursor to the right roughly by a word |
| Ctrl + Left Arrow | Move cursor to the left roughly by a word |
| Ctrl + C | Copy the selection to the clipboard, removing prompts, if any |
| Ctrl + Shift + C | Copy the selection including the prompts, if any, to the clipboard |
| Ctrl + X | Cut the selection to the clipboard |
| Ctrl + V | Paste the clipboard contents at the cursor location |
| Ctrl + Shift + V | Paste and run the current multi-line clipboard contents |
| Ctrl + Enter | Inserts a blank line between existing lines in a multiline command. |
| Ctrl + Up Arrow | Retrieve previous History item |
| Alt + P | Retrieve previous History item |
| Ctrl + Down Arrow | Retrieve next History item |
| Alt + N | Retrieve next History item |
| Shift + Up Arrow | Insert previous History item at cursor position |
| Shift + Down Arrow | Insert next History item at cursor position |
| F8 | Retrieve a specific History item by typing its first few characters and then pressing F8 |
| Ctrl+] | Increase font size |
| Ctrl+[ | Decrease font size |
| Ctrl+= | Default font size |
Auto-Completion in the Shell
One of the biggest time-saving features built into the PythonCard shell is auto-completion. Whenever you type a period in identifying a Python or PythonCard object, method, or property, the shell displays a popup menu with all of the legal completions to that statement that the shell knows about. For example, in Figure 4, we imported the standard "os" module and then typed "os" followed by a period. The popup menu shown in the figure appears.
Figure 4. Auto-CompletionPopup Menu
There are three ways to find the text you wish to type to complete this portion of the descriptor:
- You can keep typing. The popup menu uses incremental search to keep scrolling to the next string that matches what you are typing.
- You can scroll the popup menu with the mouse in the usual way and select the proper completion string.
- You can use the arrow keys to move around inside the popup menu and select the proper completion string.
Once you have selected the completion string you want, you can press Enter or the Tab key to insert it into the text at the insertion point.
If the auto-completion menu gets in your way, you can click anywhere outside its boundaries or simply press the ESCape key to close it.
You can turn this auto-completion feature on and off by typing appropriate commands in the shell. To turn the feature on, type in the shell:
shell.autoComplete = True
To turn the feature off, substitute a False for True in the above command.
Special Python attributes are prefixed with underscore characters. Some of these attributes use only a single underscore while others use two. You can include or exclude each of these types of attributes in the auto-completion list that appears in the shell by setting two different variables: autoCompleteIncludeSingle and autoCompleteIncludeDouble. For example, to exclude attributes preceded by single underscores from the list, type:
shell.autoCompleteIncludeSingle = False
Similarly, setting autoCompleteIncludeSingle to a value of True will include those attributes. The same is true for the autoCompleteIncludeDouble setting. If you want to see all of the underlying wxPython methods for a component, background, etc. then type:
shell.autoCompleteWxMethods = True
The defaults for these attributes are defined in your pycrustrc.py along with the commands that are automatically run when your shell first starts up. They are defined as:
shell.autoCompleteIncludeMagic = True shell.autoCompleteIncludeSingle = False shell.autoCompleteIncludeDouble = False shell.autoCompleteWxMethods = False
Python objects include another type of attribute, often referred to as "magic attributes." These attributes' values can only be obtained by calling the object's _getAttributeNames() method, if it has one. You can determine whether these attributes are included in the auto-completion popup by setting the variable autoCompleteIncludeMagic to True to include them, False to exclude them:
shell.autoCompleteIncludeMagic = True
Documentation Auto-Display in the Shell
Similarly to the auto-completion popup described in the preceding section, the PythonCard shell also includes the ability to automatically display important documentation for any function or method. Simply type the method or function name and the opening (left) parenthesis and the shell displays helpful information describing the function. These "call tips" attempt to display on their first line all of the arguments expected by a callable object. Where the object involved is the class name, the arguments expected by the class constructor are displayed. The second line of the call tip displays the docstring for the object if it has one.
Figure 5 demonstrates this feature. We have typed "os.fdopen(" and the resulting tool tip tells us the required and optional parameters and what the function does as well as what it returns.
Figure 5. Tool Tip Shows Documentation String While Typing Functions and Methods
Virtually all of PythonCard's built-in functions and methods have docstrings associated with them or will have prior to the final release of the product.
Editing and Retrieving Functions and Compound Statements in the Shell
You can copy, paste, edit, and execute multi-line functions and compound statements in the PythonCard shell. This can be a huge time-saver when you want to re-execute a method you've defined in the interactive editor. To do so, simply use any of the history retrieval methods outlined in Table 1 to copy any group of multiple lines and then edit them in place. If you, e.g., define a function or class in the shell and you make a mistake, you can avoid the usually mandatory complete re-typing of the code by copying the whole thing and then editing the mistakes. You can also use the PythonCard shell in conjunction with another Python-aware editor. You could, e.g., create a class in another editor, then copy its definition and paste it into the shell to experiment with it. Each time you need a new copy of the class definition, simply paste it again.
You may find yourself occasionally wanting to re-execute multiple commands , each of which may be a single line or a multi-line command. In that situation, pasting those lines into the shell using Shift+Ctrl+V will paste all the lines and run all of the commands contained in the selection.
If you want to copy multi-line commands from the shell into another file (e.g., for documentation purposes), you can select and then use Ctrl+C to copy those lines. This will strip the Python shell prompts out of the copied material. If, however, you wish to retain those prompts, use Shift+Ctrl+C to perform the copy and the prompts will be preserved when you paste the selection into another window or file.
$Revision: 1.7 $ : $Author: alextweedly $ : Last updated $Date: 2006/04/06 11:00:25 $