[Python-checkins] cpython: Issue #5066: Update IDLE docs
andrew.svetlov
python-checkins at python.org
Mon Jan 14 18:27:49 CET 2013
http://hg.python.org/cpython/rev/d1ef91025d70
changeset: 81499:d1ef91025d70
parent: 81497:831f49cc00fc
user: Andrew Svetlov <andrew.svetlov at gmail.com>
date: Mon Jan 14 19:27:36 2013 +0200
summary:
Issue #5066: Update IDLE docs
Patch by Todd Rovito
files:
Doc/library/idle.rst | 343 ++++++++++++++++----
Lib/idlelib/NEWS.txt | 2 +
Lib/idlelib/help.txt | 498 +++++++++++++++++-------------
Misc/NEWS | 2 +
4 files changed, 558 insertions(+), 287 deletions(-)
diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
--- a/Doc/library/idle.rst
+++ b/Doc/library/idle.rst
@@ -16,70 +16,82 @@
* coded in 100% pure Python, using the :mod:`tkinter` GUI toolkit
-* cross-platform: works on Windows and Unix
+* cross-platform: works on Windows, Unix, and Mac OS X
-* multi-window text editor with multiple undo, Python colorizing and many other
- features, e.g. smart indent and call tips
+* multi-window text editor with multiple undo, Python colorizing,
+ smart indent, call tips, and many other features
* Python shell window (a.k.a. interactive interpreter)
-* debugger (not complete, but you can set breakpoints, view and step)
+* debugger (not complete, but you can set breakpoints, view and step)
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).
-File menu
-^^^^^^^^^
+File menu (Shell and Editor)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New window
- create a new editing window
+ Create a new editing window
Open...
- open an existing file
+ Open an existing file
Open module...
- open an existing module (searches sys.path)
+ Open an existing module (searches sys.path)
+
+Recent Files
+ Open a list of recent files
Class browser
- show classes and methods in current file
+ Show classes and methods in current file
Path browser
- show sys.path directories, modules, classes and methods
+ Show sys.path directories, modules, classes and methods
.. index::
single: Class browser
single: Path browser
Save
- save current window to the associated file (unsaved windows have a \* before and
- after the window title)
+ Save current window to the associated file (unsaved windows have a
+ \* before and after the window title)
Save As...
- save current window to new file, which becomes the associated file
+ Save current window to new file, which becomes the associated file
Save Copy As...
- save current window to different file without changing the associated file
+ Save current window to different file without changing the associated file
+
+Print Window
+ Print the current window
Close
- close current window (asks to save if unsaved)
+ Close current window (asks to save if unsaved)
Exit
- close all windows and quit IDLE (asks to save if unsaved)
+ Close all windows and quit IDLE (asks to save if unsaved)
-Edit menu
-^^^^^^^^^
+Edit menu (Shell and Editor)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Undo
- Undo last change to current window (max 1000 changes)
+ Undo last change to current window (a maximum of 1000 changes may be undone)
Redo
Redo last undone change to current window
Cut
- Copy selection into system-wide clipboard; then delete selection
+ Copy selection into system-wide clipboard; then delete the selection
Copy
Copy selection into system-wide clipboard
@@ -108,11 +120,30 @@
Go to line
Ask for a line number and show that line
+Expand word
+ Expand the word you have typed to match another word in the same buffer;
+ repeat to get a different expansion
+
+Show call tip
+ After an unclosed parenthesis for a function, open a small window with
+ function parameter hints
+
+Show surrounding parens
+ Highlight the surrounding parenthesis
+
+Show Completions
+ Open a scroll window allowing selection keywords and attributes. See
+ Completions below.
+
+
+Format menu (Editor window only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
Indent region
- Shift selected lines right 4 spaces
+ Shift selected lines right by the indent width (default 4 spaces)
Dedent region
- Shift selected lines left 4 spaces
+ Shift selected lines left by the indent width (default 4 spaces)
Comment out region
Insert ## in front of selected lines
@@ -121,67 +152,121 @@
Remove leading # or ## from selected lines
Tabify region
- Turns *leading* stretches of spaces into tabs
+ Turns *leading* stretches of spaces into tabs. (Note: We recommend using
+ 4 space blocks to indent Python code.)
Untabify region
- Turn *all* tabs into the right number of spaces
+ Turn *all* tabs into the correct number of spaces
-Expand word
- Expand the word you have typed to match another word in the same buffer; repeat
- to get a different expansion
+Toggle tabs
+ Open a dialog to switch between indenting with spaces and tabs.
+
+New Indent Width
+ Open a dialog to change indent width. The accepted default by the Python
+ community is 4 spaces.
Format Paragraph
- Reformat the current blank-line-separated paragraph
+ Reformat the current blank-line-separated paragraph. All lines in the
+ paragraph will be formatted to less than 80 columns.
-Import module
- Import or reload the current module
-
-Run script
- Execute the current file in the __main__ namespace
+Strip trailing whitespace
+ Removes any space characters after the end of the last non-space character
.. index::
single: Import module
single: Run script
-Windows menu
-^^^^^^^^^^^^
+Run menu (Editor window only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Zoom Height
- toggles the window between normal size (24x80) and maximum height.
+Python Shell
+ Open or wake up the Python Shell window
-The rest of this menu lists the names of all open windows; select one to bring
-it to the foreground (deiconifying it if necessary).
+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.
+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.
-Debug menu
-^^^^^^^^^^
+Shell menu (Shell window only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-* in the Python Shell window only
+View Last Restart
+ Scroll the shell window to the last Shell restart
+
+Restart Shell
+ 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.
+ exception traceback. Available in the context menu of the Shell window.
-Debugger
- Run commands in the shell under the debugger.
+Debugger (toggle)
+ This feature is not complete and considered experimental. Run commands in
+ the shell under the debugger
Stack viewer
- Show the stack traceback of the last exception.
+ Show the stack traceback of the last exception
Auto-open Stack Viewer
- Open stack viewer on traceback.
+ Toggle automatically opening the stack viewer on unhandled exception
.. index::
single: stack viewer
single: debugger
+Options menu (Shell and Editor)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Edit context menu
-^^^^^^^^^^^^^^^^^
+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.
-* Right-click in Edit window (Control-click on OS X)
+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.
+
+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.
+
+The rest of this menu lists the names of all open windows; select one to bring
+it to the foreground (deiconifying it if necessary).
+
+Help menu (Shell and Editor)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+About IDLE
+ Version, copyright, license, credits
+
+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
+ and open docs.python.org showing the latest Python documentation.
+
+Additional help sources may be added here with the Configure IDLE dialog under
+the General tab.
+
+Editor Window context menu
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Right-click in Editor window (Control-click on OS X)
Cut
Copy selection into system-wide clipboard; then delete selection
@@ -207,8 +292,8 @@
single: breakpoints
-Shell context menu
-^^^^^^^^^^^^^^^^^^
+Shell Window context menu
+^^^^^^^^^^^^^^^^^^^^^^^^^
* Right-click in Python Shell window (Control-click on OS X)
@@ -225,19 +310,44 @@
Same as in Debug menu.
-Basic editing and navigation
-----------------------------
+Editing and navigation
+----------------------
* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right
+* :kbd:`C-Backspace` delete word left; :kbd:`C-Del` delete word to the right
+
* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around
+* :kbd:`C-LeftArrow` and :kbd:`C-RightArrow` moves by words
+
* :kbd:`Home`/:kbd:`End` go to begin/end of line
* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file
-* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`,
- :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L`
+* Some useful Emacs bindings are inherited from Tcl/Tk:
+
+ * :kbd:`C-a` beginning of line
+
+ * :kbd:`C-e` end of line
+
+ * :kbd:`C-k` kill line (but doesn't put it in clipboard)
+
+ * :kbd:`C-l` center window around the insertion point
+
+ * :kbd:`C-b` go backwards one character without deleting (usually you can
+ also use the cursor key for this)
+
+ * :kbd:`C-f` go forward one character without deleting (usually you can
+ also use the cursor key for this)
+
+ * :kbd:`C-p` go up one line (usually you can also use the cursor key for
+ this)
+
+ * :kbd:`C-d` delete next character
+
+Standard keybindings (like :kbd:`C-c` to copy and :kbd:`C-v` to paste)
+may work. Keybindings are selected in the Configure IDLE dialog.
Automatic indentation
@@ -246,27 +356,76 @@
After a block-opening statement, the next line is indented by 4 spaces (in the
Python Shell window by one tab). After certain keywords (break, return etc.)
the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up
-to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python
-Shell window one tab). See also the indent/dedent region commands in the edit
-menu.
+to 4 spaces if they are there. :kbd:`Tab` inserts spaces (in the Python
+Shell window one tab), number depends on Indent width. Currently tabs
+are restricted to four spaces due to Tcl/Tk limitations.
+See also the indent/dedent region commands in the edit menu.
+
+Completions
+^^^^^^^^^^^
+
+Completions are supplied for functions, classes, and attributes of classes,
+both built-in and user-defined. Completions are also provided for
+filenames.
+
+The AutoCompleteWindow (ACW) will open after a predefined delay (default is
+two seconds) after a '.' or (in a string) an os.sep is typed. If after one
+of those characters (plus zero or more other characters) a tab is typed
+the ACW will open immediately if a possible continuation is found.
+
+If there is only one possible completion for the characters entered, a
+:kbd:`Tab` will supply that completion without opening the ACW.
+
+'Show Completions' will force open a completions window, by default the
+:kbd:`C-space` will open a completions window. In an empty
+string, this will contain the files in the current directory. On a
+blank line, it will contain the built-in and user-defined functions and
+classes in the current name spaces, plus any modules imported. If some
+characters have been entered, the ACW will attempt to be more specific.
+
+If a string of characters is typed, the ACW selection will jump to the
+entry most closely matching those characters. Entering a :kbd:`tab` will
+cause the longest non-ambiguous match to be entered in the Editor window or
+Shell. Two :kbd:`tab` in a row will supply the current ACW selection, as
+will return or a double click. Cursor keys, Page Up/Down, mouse selection,
+and the scroll wheel all operate on the ACW.
+
+"Hidden" attributes can be accessed by typing the beginning of hidden
+name after a '.', e.g. '_'. This allows access to modules with
+``__all__`` set, or to class-private attributes.
+
+Completions and the 'Expand Word' facility can save a lot of typing!
+
+Completions are currently limited to those in the namespaces. Names in
+an Editor window which are not via ``__main__`` and :data:`sys.modules` will
+not be found. Run the module once with your imports to correct this situation.
+Note that IDLE itself places quite a few modules in sys.modules, so
+much can be found by default, e.g. the re module.
+
+If you don't like the ACW popping up unbidden, simply make the delay
+longer or disable the extension. Or another option is the delay could
+be set to zero. Another alternative to preventing ACW popups is to
+disable the call tips extension.
Python Shell window
^^^^^^^^^^^^^^^^^^^
-* :kbd:`C-C` interrupts executing command
+* :kbd:`C-c` interrupts executing command
-* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt
+* :kbd:`C-d` sends end-of-file; closes window if typed at a ``>>>`` prompt
+ (this is :kbd:`C-z` on Windows).
-* :kbd:`Alt-p` retrieves previous command matching what you have typed
+* :kbd:`Alt-/` (Expand word) is also useful to reduce typing
-* :kbd:`Alt-n` retrieves next
+ Command history
-* :kbd:`Return` while on any previous command retrieves that command
+ * :kbd:`Alt-p` retrieves previous command matching what you have typed. On
+ OS X use :kbd:`C-p`.
-* :kbd:`Alt-/` (Expand word) is also useful here
+ * :kbd:`Alt-n` retrieves next. On OS X use :kbd:`C-n`.
-.. index:: single: indentation
+ * :kbd:`Return` while on any previous command retrieves that command
Syntax colors
@@ -308,17 +467,17 @@
Upon startup with the ``-s`` option, IDLE will execute the file referenced by
the environment variables :envvar:`IDLESTARTUP` or :envvar:`PYTHONSTARTUP`.
-Idle first checks for ``IDLESTARTUP``; if ``IDLESTARTUP`` is present the file
-referenced is run. If ``IDLESTARTUP`` is not present, Idle checks for
+IDLE first checks for ``IDLESTARTUP``; if ``IDLESTARTUP`` is present the file
+referenced is run. If ``IDLESTARTUP`` is not present, IDLE checks for
``PYTHONSTARTUP``. Files referenced by these environment variables are
-convenient places to store functions that are used frequently from the Idle
+convenient places to store functions that are used frequently from the IDLE
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.
+to be used from IDLE's Python shell.
Command line usage
@@ -349,3 +508,45 @@
the arguments are still available in ``sys.argv``.
+Additional help sources
+-----------------------
+
+IDLE includes a help menu entry called "Python Docs" that will open the
+extensive sources of help, including tutorials, available at docs.python.org.
+Selected URLs can be added or removed from the help menu at any time using the
+Configure IDLE dialog. See the IDLE help option in the help menu of IDLE for
+more information.
+
+
+Other preferences
+-----------------
+
+The font preferences, highlighting, keys, and general preferences can be
+changed via the Configure IDLE menu option. Be sure to note that
+keys can be user defined, IDLE ships with four built in key sets. In
+addition a user can create a custom key set in the Configure IDLE dialog
+under the keys tab.
+
+Extensions
+----------
+
+IDLE contains an extension facility. See the beginning of
+config-extensions.def in the idlelib directory for further information. The
+default extensions are currently:
+
+* FormatParagraph
+
+* AutoExpand
+
+* ZoomHeight
+
+* ScriptBinding
+
+* CallTips
+
+* ParenMatch
+
+* AutoComplete
+
+* CodeContext
+
diff --git a/Lib/idlelib/NEWS.txt b/Lib/idlelib/NEWS.txt
--- a/Lib/idlelib/NEWS.txt
+++ b/Lib/idlelib/NEWS.txt
@@ -1,6 +1,8 @@
What's New in IDLE 3.4.0?
=========================
+- Issue #5066: Update IDLE docs. Patch by Todd Rovito.
+
- Issue #16226: Fix IDLE Path Browser crash.
(Patch by Roger Serwy)
diff --git a/Lib/idlelib/help.txt b/Lib/idlelib/help.txt
--- a/Lib/idlelib/help.txt
+++ b/Lib/idlelib/help.txt
@@ -1,142 +1,185 @@
[See the end of this file for ** TIPS ** on using IDLE !!]
-Click on the dotted line at the top of a menu to "tear it off": a
-separate window containing the menu is created.
+IDLE is the Python IDE built with the tkinter GUI toolkit.
-File Menu:
+IDLE has the following features:
+-coded in 100% pure Python, using the tkinter GUI toolkit
+-cross-platform: works on Windows, Unix, and OS X
+-multi-window text editor with multiple undo, Python colorizing, smart indent,
+call tips, and many other features
+-Python shell window (a.k.a interactive interpreter)
+-debugger (not complete, but you can set breakpoints, view and step)
- New Window -- Create a new editing window
- Open... -- Open an existing file
- Recent Files... -- Open a list of recent files
- Open Module... -- Open an existing module (searches sys.path)
- Class Browser -- Show classes and methods in current file
- Path Browser -- Show sys.path directories, modules, classes
+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).
+
+File Menu (Shell and Editor):
+
+ New Window -- Create a new editing window
+ Open... -- Open an existing file
+ Open Module... -- Open an existing module (searches sys.path)
+ Recent Files... -- Open a list of recent files
+ Class Browser -- Show classes and methods in current file
+ Path Browser -- Show sys.path directories, modules, classes,
and methods
- ---
- Save -- Save current window to the associated file (unsaved
- windows have a * before and after the window title)
+ ---
+ Save -- Save current window to the associated file (unsaved
+ windows have a * before and after the window title)
- Save As... -- Save current window to new file, which becomes
- the associated file
- Save Copy As... -- Save current window to different file
- without changing the associated file
- ---
- Print Window -- Print the current window
- ---
- Close -- Close current window (asks to save if unsaved)
- Exit -- Close all windows, quit (asks to save if unsaved)
+ Save As... -- Save current window to new file, which becomes
+ the associated file
+ Save Copy As... -- Save current window to different file
+ without changing the associated file
+ ---
+ Print Window -- Print the current window
+ ---
+ Close -- Close current window (asks to save if unsaved)
+ Exit -- Close all windows, quit (asks to save if unsaved)
-Edit Menu:
+Edit Menu (Shell and Editor):
- Undo -- Undo last change to current window
- (A maximum of 1000 changes may be undone)
- Redo -- Redo last undone change to current window
- ---
- Cut -- Copy a selection into system-wide clipboard,
+ Undo -- Undo last change to current window
+ (a maximum of 1000 changes may be undone)
+ Redo -- Redo last undone change to current window
+ ---
+ Cut -- Copy a selection into system-wide clipboard,
then delete the selection
- Copy -- Copy selection into system-wide clipboard
- Paste -- Insert system-wide clipboard into window
- Select All -- Select the entire contents of the edit buffer
- ---
- Find... -- Open a search dialog box with many options
- Find Again -- Repeat last search
- Find Selection -- Search for the string in the selection
- Find in Files... -- Open a search dialog box for searching files
- Replace... -- Open a search-and-replace dialog box
- Go to Line -- Ask for a line number and show that line
- Show Calltip -- Open a small window with function param hints
- Show Completions -- Open a scroll window allowing selection keywords
- and attributes. (see '*TIPS*', below)
- Show Parens -- Highlight the surrounding parenthesis
- Expand Word -- Expand the word you have typed to match another
- word in the same buffer; repeat to get a
+ Copy -- Copy selection into system-wide clipboard
+ Paste -- Insert system-wide clipboard into window
+ Select All -- Select the entire contents of the edit buffer
+ ---
+ Find... -- Open a search dialog box with many options
+ Find Again -- Repeat last search
+ Find Selection -- Search for the string in the selection
+ Find in Files... -- Open a search dialog box for searching files
+ Replace... -- Open a search-and-replace dialog box
+ Go to Line -- Ask for a line number and show that line
+ Expand Word -- Expand the word you have typed to match another
+ word in the same buffer; repeat to get a
different expansion
+ Show Calltip -- After an unclosed parenthesis for a function, open
+ a small window with function parameter hints
+ Show Parens -- Highlight the surrounding parenthesis
+ Show Completions -- Open a scroll window allowing selection keywords
+ and attributes. (see '*TIPS*', below)
-Format Menu (only in Edit window):
+Format Menu (Editor window only):
- Indent Region -- Shift selected lines right 4 spaces
- Dedent Region -- Shift selected lines left 4 spaces
- Comment Out Region -- Insert ## in front of selected lines
- Uncomment Region -- Remove leading # or ## from selected lines
- Tabify Region -- Turns *leading* stretches of spaces into tabs
- (Note: We recommend using 4 space blocks to indent Python code.)
- Untabify Region -- Turn *all* tabs into the right number of spaces
- New Indent Width... -- Open dialog to change indent width
- Format Paragraph -- Reformat the current blank-line-separated
- paragraph
+ 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)
+ Comment Out Region -- Insert ## in front of selected lines
+ Uncomment Region -- Remove leading # or ## from selected lines
+ Tabify Region -- Turns *leading* stretches of spaces into tabs.
+ (Note: We recommend using 4 space blocks to indent Python code.)
+ Untabify Region -- Turn *all* tabs into the corrent number of spaces
+ Toggle tabs -- Open a dialog to switch between indenting with
+ spaces and tabs.
+ New Indent Width... -- Open a dialog to change indent width. The
+ accepted default by the Python 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.
+ ---
+ Strip trailing whitespace -- Removed any space characters after the end
+ of the last non-space character
-Run Menu (only in Edit window):
+Run Menu (Editor window only):
- Python Shell -- Open or wake up the Python shell window
- ---
- Check Module -- Run a syntax check on the module
- Run Module -- Execute the current file in the __main__ namespace
+ Python Shell -- Open or wake up the Python shell window
+ ---
+ 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.
+ 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.
-Shell Menu (only in Shell window):
+Shell Menu (Shell window only):
- View Last Restart -- Scroll the shell window to the last restart
- Restart Shell -- Restart the interpreter with a fresh environment
+ View Last Restart -- Scroll the shell window to the last Shell restart
+ Restart Shell -- Restart the shell to clean the environment
-Debug Menu (only in Shell window):
+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
- Debugger (toggle) -- Run commands in the shell under the debugger
- Stack Viewer -- Show the stack traceback of the last exception
- Auto-open Stack Viewer (toggle) -- Open stack viewer on traceback
+ 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.
+ Debugger (toggle) -- This feature is not complete and considered
+ experimental. Run commands in the shell under the
+ debugger.
+ Stack Viewer -- Show the stack traceback of the last exception
+ Auto-open Stack Viewer (toggle) -- Toggle automatically opening the
+ stack viewer on unhandled
+ exception
-Options Menu:
+Options Menu (Shell and Editor):
- Configure IDLE -- Open a configuration dialog. Fonts, indentation,
+ 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.
-
- On OS X this menu is not present, use
- menu 'IDLE -> Preferences...' instead.
- ---
- Code Context -- 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 or the window.
- (Not present in Shell window.)
+ Startup Preferences may be set, and additional Help
+ sources can be specified.
-Windows Menu:
+ ---
+ Code Context (toggle) -- 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 or the
+ window. This is not present in the Shell
+ window only the Editor window.
- Zoom Height -- toggles the window between configured size
- and maximum height.
- ---
- The rest of this menu lists the names of all open windows;
- select one to bring it to the foreground (deiconifying it if
- necessary).
+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.
+ ---
+ The rest of this menu lists the names of all open windows;
+ select one to bring it to the foreground (deiconifying it if
+ necessary).
Help Menu:
- About IDLE -- Version, copyright, license, credits
- IDLE Readme -- Background discussion and change details
- ---
- IDLE Help -- Display this file
- Python Docs -- Access local Python documentation, if
- installed. Otherwise, access www.python.org.
- ---
- (Additional Help Sources may be added here)
+ About IDLE -- Version, copyright, license, credits
+ ---
+ IDLE Help -- Display this file which is 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 and open
+ docs.python.org showing the latest Python documentation.
+ ---
+ Additional help sources may be added here with the Configure IDLE
+ dialog under the General tab.
-Edit context menu (Right-click / Control-click on OS X in Edit window):
+Editor context menu (Right-click / Control-click on OS X in Edit window):
- Cut -- Copy a selection into system-wide clipboard,
+ Cut -- Copy a selection into system-wide clipboard,
then delete the selection
- Copy -- Copy selection into system-wide clipboard
- Paste -- Insert system-wide clipboard into window
- Set Breakpoint -- Sets a breakpoint (when debugger open)
- Clear Breakpoint -- Clears the breakpoint on that line
+ Copy -- Copy selection into system-wide clipboard
+ Paste -- Insert system-wide clipboard into window
+ Set Breakpoint -- Sets a breakpoint. Breakpoints are only enabled
+ when the debugger is open.
+ Clear Breakpoint -- Clears the breakpoint on that line
Shell context menu (Right-click / Control-click on OS X in Shell window):
- Cut -- Copy a selection into system-wide clipboard,
+ Cut -- Copy a selection into system-wide clipboard,
then delete the selection
- Copy -- Copy selection into system-wide clipboard
- Paste -- Insert system-wide clipboard into window
- ---
- Go to file/line -- Same as in Debug menu
+ Copy -- Copy selection into system-wide clipboard
+ Paste -- Insert system-wide clipboard into window
+ ---
+ Go to file/line -- Same as in Debug menu
** TIPS **
@@ -144,160 +187,183 @@
Additional Help Sources:
- Windows users can Google on zopeshelf.chm to access Zope help files in
- the Windows help format. The Additional Help Sources feature of the
- configuration GUI supports .chm, along with any other filetypes
- supported by your browser. Supply a Menu Item title, and enter the
- location in the Help File Path slot of the New Help Source dialog. Use
- http:// and/or www. to identify external URLs, or download the file and
- browse for its path on your machine using the Browse button.
+ Windows users can Google on zopeshelf.chm to access Zope help files in
+ the Windows help format. The Additional Help Sources feature of the
+ configuration GUI supports .chm, along with any other filetypes
+ supported by your browser. Supply a Menu Item title, and enter the
+ location in the Help File Path slot of the New Help Source dialog. Use
+ http:// and/or www. to identify external URLs, or download the file and
+ browse for its path on your machine using the Browse button.
- All users can access the extensive sources of help, including
- tutorials, available at www.python.org/doc. Selected URLs can be added
- or removed from the Help menu at any time using Configure IDLE.
+ All users can access the extensive sources of help, including
+ tutorials, available at docs.python.org. Selected URLs can be added
+ or removed from the Help menu at any time using Configure IDLE.
Basic editing and navigation:
- Backspace deletes char to the left; DEL deletes char to the right.
- Control-backspace deletes word left, Control-DEL deletes word right.
- Arrow keys and Page Up/Down move around.
- Control-left/right Arrow moves by words in a strange but useful way.
- Home/End go to begin/end of line.
- Control-Home/End go to begin/end of file.
- Some useful Emacs bindings are inherited from Tcl/Tk:
- Control-a beginning of line
- Control-e end of line
- Control-k kill line (but doesn't put it in clipboard)
- Control-l center window around the insertion point
- Standard Windows bindings may work on that platform.
- Keybindings are selected in the Settings Dialog, look there.
+ Backspace deletes char to the left; DEL deletes char to the right.
+ Control-backspace deletes word left, Control-DEL deletes word right.
+ Arrow keys and Page Up/Down move around.
+ Control-left/right Arrow moves by words in a strange but useful way.
+ Home/End go to begin/end of line.
+ Control-Home/End go to begin/end of file.
+ Some useful Emacs bindings are inherited from Tcl/Tk:
+ Control-a beginning of line
+ Control-e end of line
+ Control-k kill line (but doesn't put it in clipboard)
+ Control-l center window around the insertion point
+ Standard keybindings (like Control-c to copy and Control-v to
+ paste) may work. Keybindings are selected in the Configure IDLE
+ dialog.
Automatic indentation:
- After a block-opening statement, the next line is indented by 4 spaces
- (in the Python Shell window by one tab). After certain keywords
- (break, return etc.) the next line is dedented. In leading
- indentation, Backspace deletes up to 4 spaces if they are there. Tab
- inserts spaces (in the Python Shell window one tab), number depends on
- Indent Width. (N.B. Currently tabs are restricted to four spaces due
- to Tcl/Tk issues.)
+ After a block-opening statement, the next line is indented by 4 spaces
+ (in the Python Shell window by one tab). After certain keywords
+ (break, return etc.) the next line is dedented. In leading
+ indentation, Backspace deletes up to 4 spaces if they are there. Tab
+ inserts spaces (in the Python Shell window one tab), number depends on
+ Indent Width. Currently tabs are restricted to four spaces due
+ to Tcl/Tk limitations.
See also the indent/dedent region commands in the edit menu.
Completions:
- Completions are supplied for functions, classes, and attributes of
- classes, both built-in and user-defined. Completions are also provided
- for filenames.
+ Completions are supplied for functions, classes, and attributes of
+ classes, both built-in and user-defined. Completions are also provided
+ for filenames.
- The AutoCompleteWindow (ACW) will open after a predefined delay
- (default is two seconds) after a '.' or (in a string) an os.sep is
- typed. If after one of those characters (plus zero or more other
- characters) you type a Tab the ACW will open immediately if a possible
- continuation is found.
+ The AutoCompleteWindow (ACW) will open after a predefined delay
+ (default is two seconds) after a '.' or (in a string) an os.sep is
+ typed. If after one of those characters (plus zero or more other
+ characters) a tab is typed the ACW will open immediately if a possible
+ continuation is found.
- If there is only one possible completion for the characters entered, a
- Tab will supply that completion without opening the ACW.
+ If there is only one possible completion for the characters entered, a
+ tab will supply that completion without opening the ACW.
- 'Show Completions' will force open a completions window. In an empty
- string, this will contain the files in the current directory. On a
- blank line, it will contain the built-in and user-defined functions and
- classes in the current name spaces, plus any modules imported. If some
- characters have been entered, the ACW will attempt to be more specific.
+ 'Show Completions' will force open a completions window, by default the
+ Control-space keys will open a completions window. In an empty
+ string, this will contain the files in the current directory. On a
+ blank line, it will contain the built-in and user-defined functions and
+ classes in the current name spaces, plus any modules imported. If some
+ characters have been entered, the ACW will attempt to be more specific.
- If string of characters is typed, the ACW selection will jump to the
- entry most closely matching those characters. Entering a Tab will cause
- the longest non-ambiguous match to be entered in the Edit window or
- Shell. Two Tabs in a row will supply the current ACW selection, as
- will Return or a double click. Cursor keys, Page Up/Down, mouse
- selection, and the scrollwheel all operate on the ACW.
+ If string of characters is typed, the ACW selection will jump to the
+ entry most closely matching those characters. Entering a tab will cause
+ the longest non-ambiguous match to be entered in the Edit window or
+ Shell. Two tabs in a row will supply the current ACW selection, as
+ will return or a double click. Cursor keys, Page Up/Down, mouse
+ selection, and the scroll wheel all operate on the ACW.
- 'Hidden' attributes can be accessed by typing the beginning of hidden
- name after a '.'. e.g. '_'. This allows access to modules with
- '__all__' set, or to class-private attributes.
+ "Hidden" attributes can be accessed by typing the beginning of hidden
+ name after a '.', e.g. '_'. This allows access to modules with
+ '__all__' set, or to class-private attributes.
- Completions and the 'Expand Word' facility can save a lot of typing!
+ Completions and the 'Expand Word' facility can save a lot of typing!
- Completions are currently limited to those in the namespaces. Names in
- an Edit window which are not via __main__ or sys.modules will not be
- found. Run the module once with your imports to correct this
- situation. Note that IDLE itself places quite a few modules in
- sys.modules, so much can be found by default, e.g. the re module.
+ Completions are currently limited to those in the namespaces. Names in
+ an Editor window which are not via __main__ or sys.modules will not be
+ found. Run the module once with your imports to correct this
+ situation. Note that IDLE itself places quite a few modules in
+ sys.modules, so much can be found by default, e.g. the re module.
- If you don't like the ACW popping up unbidden, simply make the delay
- longer or disable the extension. OTOH, you could make the delay zero.
-
- You could also switch off the CallTips extension. (We will be adding
- a delay to the call tip window.)
+ If you don't like the ACW popping up unbidden, simply make the delay
+ longer or disable the extension. Or another option is the delay could
+ be set to zero. Another alternative to preventing ACW popups is to
+ disable the call tips extension.
Python Shell window:
- Control-c interrupts executing command.
- Control-d sends end-of-file; closes window if typed at >>> prompt
- (this is Control-z on Windows).
+ Control-c interrupts executing command.
+ Control-d sends end-of-file; closes window if typed at >>> prompt
+ (this is Control-z on Windows).
+ Alt-/ expand word is also useful to reduce typing.
Command history:
- Alt-p retrieves previous command matching what you have typed.
- Alt-n retrieves next.
- (These are Control-p, Control-n on OS X)
- Return while cursor is on a previous command retrieves that command.
- Expand word is also useful to reduce typing.
+ Alt-p retrieves previous command matching what you have typed. On OS X
+ use Control-p.
+ Alt-n retrieves next. On OS X use Control-n.
+ Return while cursor is on a previous command retrieves that command.
Syntax colors:
- The coloring is applied in a background "thread", so you may
- occasionally see uncolorized text. To change the color
- scheme, use the Configure IDLE / Highlighting dialog.
+ The coloring is applied in a background "thread", so you may
+ occasionally see uncolorized text. To change the color
+ scheme, use the Configure IDLE / Highlighting dialog.
Python default syntax colors:
- Keywords orange
- Builtins royal purple
- Strings green
- Comments red
- Definitions blue
+ Keywords orange
+ Builtins royal purple
+ Strings green
+ Comments red
+ Definitions blue
Shell default colors:
- Console output brown
- stdout blue
- stderr red
- stdin black
+ Console output brown
+ stdout blue
+ stderr red
+ stdin black
Other preferences:
- The font preferences, keybinding, and startup preferences can
- be changed using the Settings dialog.
+ The font preferences, highlighting, keys, and general preferences can
+ be changed via the Configure IDLE menu option. Be sure to note that
+ keys can be user defined, IDLE ships with four built in key sets. In
+ addition a user can create a custom key set in the Configure IDLE
+ dialog under the keys tab.
Command line usage:
- Enter idle -h at the command prompt to get a usage message.
+ Enter idle -h at the command prompt to get a usage message.
-Running without a subprocess: (DEPRECATED)
+ idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ...
- If IDLE is started with the -n command line switch it will run in a
- single process and will not create the subprocess which runs the RPC
- Python execution server. This can be useful if Python cannot create
- the subprocess or the RPC socket interface on your platform. However,
- in this mode user code is not isolated from IDLE itself. Also, the
- environment is not restarted when Run/Run Module (F5) is selected. If
- your code has been modified, you must reload() the affected modules and
- re-import any specific items (e.g. from foo import baz) if the changes
- are to take effect. For these reasons, it is preferable to run IDLE
- with the default subprocess if at all possible.
+ -c command run this command
+ -d enable debugger
+ -e edit mode; arguments are files to be edited
+ -s run $IDLESTARTUP or $PYTHONSTARTUP first
+ -t title set title of shell window
+
+ If there are arguments:
+ 1. If -e is used, arguments are files opened for editing and sys.argv
+ reflects the arguments passed to IDLE itself.
+ 2. Otherwise, if -c is used, all arguments are placed in
+ sys.argv[1:...], with sys.argv[0] set to -c.
+ 3. 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.
+
+Running without a subprocess: (DEPRECATED in Python 3.5 see Issue 16123)
+
+ If IDLE is started with the -n command line switch it will run in a
+ single process and will not create the subprocess which runs the RPC
+ Python execution server. This can be useful if Python cannot create
+ the subprocess or the RPC socket interface on your platform. However,
+ in this mode user code is not isolated from IDLE itself. Also, the
+ environment is not restarted when Run/Run Module (F5) is selected. If
+ your code has been modified, you must reload() the affected modules and
+ re-import any specific items (e.g. from foo import baz) if the changes
+ are to take effect. For these reasons, it is preferable to run IDLE
+ with the default subprocess if at all possible.
Extensions:
- IDLE contains an extension facility. See the beginning of
- config-extensions.def in the idlelib directory for further information.
- The default extensions are currently:
+ IDLE contains an extension facility. See the beginning of
+ config-extensions.def in the idlelib directory for further information.
+ The default extensions are currently:
- FormatParagraph
- AutoExpand
- ZoomHeight
- ScriptBinding
- CallTips
- ParenMatch
- AutoComplete
- CodeContext
+ FormatParagraph
+ AutoExpand
+ ZoomHeight
+ ScriptBinding
+ CallTips
+ ParenMatch
+ AutoComplete
+ CodeContext
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -217,6 +217,8 @@
Library
-------
+- Issue #5066: Update IDLE docs. Patch by Todd Rovito.
+
- Issue #16955: Fix the poll() method for multiprocessing's socket
connections on Windows.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list