summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Doc/library/idle.rst261
1 files changed, 138 insertions, 123 deletions
diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
index f62f863..e9a91ae 100644
--- a/Doc/library/idle.rst
+++ b/Doc/library/idle.rst
@@ -29,136 +29,147 @@ IDLE has the following features:
Menus
-----
-IDLE has two window types, the Shell window and the Editor window. It is
-possible to have multiple editor windows simultaneously. IDLE's
-menus dynamically change based on which window is currently selected. Each menu
-documented below indicates which window type it is associated with. Click on
-the dotted line at the top of a menu to "tear it off": a separate window
-containing the menu is created (for Unix and Windows only).
+IDLE has two main window types, the Shell window and the Editor window. It is
+possible to have multiple editor windows simultaneously. Output windows, such
+as used for Edit / Find in Files, are a subtype of edit window. They currently
+have the same top menu as Editor windows but a different default title and
+context menu.
+
+IDLE's menus dynamically change based on which window is currently selected.
+Each menu documented below indicates which window type it is associated with.
+Click on the dotted line at the top of a menu to "tear it off": a separate
+window containing the menu is created (for Unix and Windows only).
File menu (Shell and Editor)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-New file
- Create a new file editing window
+New File
+ Create a new file editing window.
Open...
- Open an existing file
-
-Open module...
- Open an existing module (searches sys.path)
+ Open an existing file with an Open dialog.
Recent Files
- Open a list of recent files
+ Open a list of recent files. Click one to open it.
+
+Open Module...
+ Open an existing module (searches sys.path).
.. index::
single: Class browser
single: Path browser
-Class browser
- Show classes and methods in current file
+Class Browser
+ Show functions, classes, and methods in the current Editor file in a
+ tree structure. In the shell, open a module first.
-Path browser
- Show sys.path directories, modules, classes and methods
+Path Browser
+ Show sys.path directories, modules, functions, classes and methods in a
+ tree structure.
Save
- Save current window to the associated file (unsaved windows have a
- \* before and after the window title)
+ Save the current window to the associated file, if there is one. Windows
+ that have been changed since being opened or last saved have a \* before
+ and after the window title. If there is no associated file,
+ do Save As instead.
Save As...
- Save current window to new file, which becomes the associated file
+ Save the current window with a Save As dialog. The file saved becomes the
+ new associated file for the window.
Save Copy As...
- Save current window to different file without changing the associated file
+ Save the current window to different file without changing the associated
+ file.
Print Window
- Print the current window
+ Print the current window to the default printer.
Close
- Close current window (asks to save if unsaved)
+ Close the current window (ask to save if unsaved).
Exit
- Close all windows and quit IDLE (asks to save if unsaved)
-
+ Close all windows and quit IDLE (ask to save unsaved windows).
Edit menu (Shell and Editor)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Undo
- Undo last change to current window (a maximum of 1000 changes may be undone)
+ Undo the last change to the current window. A maximum of 1000 changes may
+ be undone.
Redo
- Redo last undone change to current window
+ Redo the last undone change to the current window.
Cut
- Copy selection into system-wide clipboard; then delete the selection
+ Copy selection into the system-wide clipboard; then delete the selection.
Copy
- Copy selection into system-wide clipboard
+ Copy selection into the system-wide clipboard.
Paste
- Insert system-wide clipboard into window
+ Insert contents of the system-wide clipboard into the current window.
+
+The clipboard functions are also available in context menus.
Select All
- Select the entire contents of the edit buffer
+ Select the entire contents of the current window.
Find...
- Open a search dialog box with many options
+ Open a search dialog with many options
-Find again
- Repeat last search
+Find Again
+ Repeat the last search, if there is one.
-Find selection
- Search for the string in the selection
+Find Selection
+ Search for the currently selected string, if there is one.
Find in Files...
- Open a search dialog box for searching files
+ Open a file search dialog. Put results in an new output window.
Replace...
- Open a search-and-replace dialog box
+ Open a search-and-replace dialog.
+
+Go to Line
+ Move cursor to the line number requested and make that line visible.
-Go to line
- Ask for a line number and show that line
+Show Completions
+ Open a scrollable list allowing selection of keywords and attributes. See
+ Completions in the Tips sections below.
-Expand word
- Expand the word you have typed to match another word in the same buffer;
- repeat to get a different expansion
+Expand Word
+ Expand a prefix you have typed to match a full word in the same window;
+ repeat to get a different expansion.
Show call tip
After an unclosed parenthesis for a function, open a small window with
- function parameter hints
+ function parameter hints.
Show surrounding parens
- Highlight the surrounding parenthesis
-
-Show Completions
- Open a scroll window allowing selection keywords and attributes. See
- Completions below.
-
+ Highlight the surrounding parenthesis.
Format menu (Editor window only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Indent region
- Shift selected lines right by the indent width (default 4 spaces)
+Indent Region
+ Shift selected lines right by the indent width (default 4 spaces).
-Dedent region
- Shift selected lines left by the indent width (default 4 spaces)
+Dedent Region
+ Shift selected lines left by the indent width (default 4 spaces).
-Comment out region
- Insert ## in front of selected lines
+Comment Out Region
+ Insert ## in front of selected lines.
-Uncomment region
- Remove leading # or ## from selected lines
+Uncomment Region
+ Remove leading # or ## from selected lines.
-Tabify region
- Turns *leading* stretches of spaces into tabs. (Note: We recommend using
+Tabify Region
+ Turn *leading* stretches of spaces into tabs. (Note: We recommend using
4 space blocks to indent Python code.)
-Untabify region
- Turn *all* tabs into the correct number of spaces
+Untabify Region
+ Turn *all* tabs into the correct number of spaces.
-Toggle tabs
+Toggle Tabs
Open a dialog to switch between indenting with spaces and tabs.
New Indent Width
@@ -166,62 +177,67 @@ New Indent Width
community is 4 spaces.
Format Paragraph
- Reformat the current blank-line-separated paragraph. All lines in the
- paragraph will be formatted to less than 80 columns.
+ Reformat the current blank-line-delimited paragraph in comment block or
+ multiline string or selected line in a string. All lines in the
+ paragraph will be formatted to less than N columns, where N defaults to 72.
Strip trailing whitespace
- Removes any space characters after the end of the last non-space character
+ Remove any space characters after the last non-space character of a line.
.. index::
- single: Import module
single: Run script
-
Run menu (Editor window only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Python Shell
- Open or wake up the Python Shell window
+ Open or wake up the Python Shell window.
-Check module
+Check Module
Check the syntax of the module currently open in the Editor window. If the
- module has not been saved IDLE will prompt the user to save the code.
+ module has not been saved IDLE will either prompt the user to save or
+ autosave, as selected in the General tab of the Idle Settings dialog. If
+ there is a syntax error, the approximate location is indicated in the
+ Editor window.
-Run module
- Restart the shell to clean the environment, then execute the currently
- open module. If the module has not been saved IDLE will prompt the user
- to save the code.
+Run Module
+ Do Check Module (above). If no error, restart the shell to clean the
+ environment, then execute the module.
Shell menu (Shell window only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
View Last Restart
- Scroll the shell window to the last Shell restart
+ Scroll the shell window to the last Shell restart.
Restart Shell
- Restart the shell to clean the environment
+ Restart the shell to clean the environment.
Debug menu (Shell window only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Go to file/line
- Look around the insert point for a filename and line number, open the file,
- and show the line. Useful to view the source lines referenced in an
- exception traceback. Available in the context menu of the Shell window.
+Go to File/Line
+ Look on the current line. with the cursor, and the line above for a filename
+ and line number. If found, open the file if not already open, and show the
+ line. Use this to view source lines referenced in an exception traceback
+ and lines found by Find in Files. Also available in the context menu of
+ the Shell window and Output windows.
+
+.. index::
+ single: debugger
+ single: stack viewer
Debugger (toggle)
- This feature is not complete and considered experimental. Run commands in
- the shell under the debugger
+ When actived, code entered in the Shell or run from an Editor will run
+ under the debugger. In the Editor, breakpoints can be set with the context
+ menu. This feature is still incomplete and somewhat experimental.
-Stack viewer
- Show the stack traceback of the last exception
+Stack Viewer
+ Show the stack traceback of the last exception in a tree widget, with
+ access to locals and globals.
Auto-open Stack Viewer
- Toggle automatically opening the stack viewer on unhandled exception
-
-.. index::
- single: stack viewer
- single: debugger
+ Toggle automatically opening the stack viewer on an unhandled exception.
Options menu (Shell and Editor)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -229,23 +245,26 @@ Options menu (Shell and Editor)
Configure IDLE
Open a configuration dialog. Fonts, indentation, keybindings, and color
themes may be altered. Startup Preferences may be set, and additional
- help sources can be specified.
+ help sources can be specified. Non-default user setting are saved in a
+ .idlerc directory in the user's home directory. Problems caused by bad user
+ configuration files are solved by editing or deleting one or more of the
+ files in .idlerc.
Configure Extensions
Open a configuration dialog for setting preferences for extensions
- (discussed below).
+ (discussed below). See note above about the location of user settings.
Code Context (toggle)(Editor Window only)
Open a pane at the top of the edit window which shows the block context
- of the section of code which is scrolling off the top of the window.
+ of the code which has scrolled above the top of the window.
Windows menu (Shell and Editor)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Zoom Height
- Toggles the window between normal size (40x80 initial setting) and maximum
- height. The initial size is in the Configure IDLE dialog under the general
- tab.
+ Toggles the window between normal size and maximum height. The initial size
+ defaults to 40 lines by 80 chars unless changed on the General tab of the
+ Configure IDLE dialog.
The rest of this menu lists the names of all open windows; select one to bring
it to the foreground (deiconifying it if necessary).
@@ -254,16 +273,19 @@ Help menu (Shell and Editor)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
About IDLE
- Version, copyright, license, credits
+ Display version, copyright, license, credits, and more.
IDLE Help
Display a help file for IDLE detailing the menu options, basic editing and
navigation, and other tips.
Python Docs
- Access local Python documentation, if installed. Or will start a web browser
+ Access local Python documentation, if installed, or start a web browser
and open docs.python.org showing the latest Python documentation.
+Turtle Demo
+ Run the turtledemo module with example python code and turtle drawings.
+
Additional help sources may be added here with the Configure IDLE dialog under
the General tab.
@@ -275,39 +297,32 @@ the General tab.
single: Clear Breakpoint
single: breakpoints
-Editor Window context menu
+Context Menus
^^^^^^^^^^^^^^^^^^^^^^^^^^
-* Right-click in Editor window (Control-click on OS X)
+Open a context menu by right-clicking in a window (Control-click on OS X).
+Context menus have the standard clipboard functions also on the Edit menu.
Cut
- Copy selection into system-wide clipboard; then delete selection
+ Copy selection into the system-wide clipboard; then delete the selection.
Copy
- Copy selection into system-wide clipboard
+ Copy selection into the system-wide clipboard.
Paste
- Insert system-wide clipboard into window
+ Insert contents of the system-wide clipboard into the current window.
+
+Editor windows also have breakpoint functions. Lines with a breakpoint set are
+specially marked. Breakpoints only have an effect when running under the
+debugger. Breakpoints for a file are saved in the user's .idlerc directory.
Set Breakpoint
- Sets a breakpoint. Breakpoints are only enabled when the debugger is open.
+ Set a breakpoint on the current line.
Clear Breakpoint
- Clears the breakpoint on that line.
+ Clear the breakpoint on that line.
-Shell Window context menu
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Right-click in Python Shell window (Control-click on OS X)
-
-Cut
- Copy selection into system-wide clipboard; then delete selection
-
-Copy
- Copy selection into system-wide clipboard
-
-Paste
- Insert system-wide clipboard into window
+Shell and Output windows have the following.
Go to file/line
Same as in Debug menu.
@@ -481,8 +496,8 @@ shell, or for executing import statements to import common modules.
In addition, ``Tk`` also loads a startup file if it is present. Note that the
Tk file is loaded unconditionally. This additional file is ``.Idle.py`` and is
looked for in the user's home directory. Statements in this file will be
-executed in the Tk namespace, so this file is not useful for importing functions
-to be used from IDLE's Python shell.
+executed in the Tk namespace, so this file is not useful for importing
+functions to be used from IDLE's Python shell.
Command line usage
@@ -508,9 +523,9 @@ If there are arguments:
#. Otherwise, if neither ``-e`` nor ``-c`` is used, the first
argument is a script which is executed with the remaining arguments in
- ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script
- name is '-', no script is executed but an interactive Python session is started;
- the arguments are still available in ``sys.argv``.
+ ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the
+ script name is '-', no script is executed but an interactive Python session
+ is started; the arguments are still available in ``sys.argv``.
Running without a subprocess
^^^^^^^^^^^^^^^^^^^^^^^^^^^^