Doc/library/idle.rst

   1 .. _idle:
   2
   3 IDLE
   4 ====
   5
   6 .. moduleauthor:: Guido van Rossum <guido@Python.org>
   7
   8 .. index::
   9    single: IDLE
  10    single: Python Editor
  11    single: Integrated Development Environment
  12
  13 IDLE is the Python IDE built with the :mod:`tkinter` GUI toolkit.
  14
  15 IDLE has the following features:
  16
  17 * coded in 100% pure Python, using the :mod:`tkinter` GUI toolkit
  18
  19 * cross-platform: works on Windows and Unix
  20
  21 * multi-window text editor with multiple undo, Python colorizing and many other
  22   features, e.g. smart indent and call tips
  23
  24 * Python shell window (a.k.a. interactive interpreter)
  25
  26 * debugger (not complete, but you can set breakpoints, view  and step)
  27
  28
  29 Menus
  30 -----
  31
  32
  33 File menu
  34 ^^^^^^^^^
  35
  36 New window
  37    create a new editing window
  38
  39 Open...
  40    open an existing file
  41
  42 Open module...
  43    open an existing module (searches sys.path)
  44
  45 Class browser
  46    show classes and methods in current file
  47
  48 Path browser
  49    show sys.path directories, modules, classes and methods
  50
  51 .. index::
  52    single: Class browser
  53    single: Path browser
  54
  55 Save
  56    save current window to the associated file (unsaved windows have a \* before and
  57    after the window title)
  58
  59 Save As...
  60    save current window to new file, which becomes the associated file
  61
  62 Save Copy As...
  63    save current window to different file without changing the associated file
  64
  65 Close
  66    close current window (asks to save if unsaved)
  67
  68 Exit
  69    close all windows and quit IDLE (asks to save if unsaved)
  70
  71
  72 Edit menu
  73 ^^^^^^^^^
  74
  75 Undo
  76    Undo last change to current window (max 1000 changes)
  77
  78 Redo
  79    Redo last undone change to current window
  80
  81 Cut
  82    Copy selection into system-wide clipboard; then delete selection
  83
  84 Copy
  85    Copy selection into system-wide clipboard
  86
  87 Paste
  88    Insert system-wide clipboard into window
  89
  90 Select All
  91    Select the entire contents of the edit buffer
  92
  93 Find...
  94    Open a search dialog box with many options
  95
  96 Find again
  97    Repeat last search
  98
  99 Find selection
 100    Search for the string in the selection
 101
 102 Find in Files...
 103    Open a search dialog box for searching files
 104
 105 Replace...
 106    Open a search-and-replace dialog box
 107
 108 Go to line
 109    Ask for a line number and show that line
 110
 111 Indent region
 112    Shift selected lines right 4 spaces
 113
 114 Dedent region
 115    Shift selected lines left 4 spaces
 116
 117 Comment out region
 118    Insert ## in front of selected lines
 119
 120 Uncomment region
 121    Remove leading # or ## from selected lines
 122
 123 Tabify region
 124    Turns *leading* stretches of spaces into tabs
 125
 126 Untabify region
 127    Turn *all* tabs into the right number of spaces
 128
 129 Expand word
 130    Expand the word you have typed to match another word in the same buffer; repeat
 131    to get a different expansion
 132
 133 Format Paragraph
 134    Reformat the current blank-line-separated paragraph
 135
 136 Import module
 137    Import or reload the current module
 138
 139 Run script
 140    Execute the current file in the __main__ namespace
 141
 142 .. index::
 143    single: Import module
 144    single: Run script
 145
 146
 147 Windows menu
 148 ^^^^^^^^^^^^
 149
 150 Zoom Height
 151    toggles the window between normal size (24x80) and maximum height.
 152
 153 The rest of this menu lists the names of all open windows; select one to bring
 154 it to the foreground (deiconifying it if necessary).
 155
 156
 157 Debug menu (in the Python Shell window only)
 158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 159
 160 Go to file/line
 161    look around the insert point for a filename and linenumber, open the file, and
 162    show the line.
 163
 164 Open stack viewer
 165    show the stack traceback of the last exception
 166
 167 Debugger toggle
 168    Run commands in the shell under the debugger
 169
 170 JIT Stack viewer toggle
 171    Open stack viewer on traceback
 172
 173 .. index::
 174    single: stack viewer
 175    single: debugger
 176
 177
 178 Basic editing and navigation
 179 ----------------------------
 180
 181 * :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right
 182
 183 * Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around
 184
 185 * :kbd:`Home`/:kbd:`End` go to begin/end of line
 186
 187 * :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file
 188
 189 * Some :program:`Emacs` bindings may also work, including :kbd:`C-B`,
 190   :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L`
 191
 192
 193 Automatic indentation
 194 ^^^^^^^^^^^^^^^^^^^^^
 195
 196 After a block-opening statement, the next line is indented by 4 spaces (in the
 197 Python Shell window by one tab).  After certain keywords (break, return etc.)
 198 the next line is dedented.  In leading indentation, :kbd:`Backspace` deletes up
 199 to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python
 200 Shell window one tab). See also the indent/dedent region commands in the edit
 201 menu.
 202
 203
 204 Python Shell window
 205 ^^^^^^^^^^^^^^^^^^^
 206
 207 * :kbd:`C-C` interrupts executing command
 208
 209 * :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt
 210
 211 * :kbd:`Alt-p` retrieves previous command matching what you have typed
 212
 213 * :kbd:`Alt-n` retrieves next
 214
 215 * :kbd:`Return` while on any previous command retrieves that command
 216
 217 * :kbd:`Alt-/` (Expand word) is also useful here
 218
 219 .. index:: single: indentation
 220
 221
 222 Syntax colors
 223 -------------
 224
 225 The coloring is applied in a background "thread," so you may occasionally see
 226 uncolorized text.  To change the color scheme, edit the ``[Colors]`` section in
 227 :file:`config.txt`.
 228
 229 Python syntax colors:
 230    Keywords
 231       orange
 232
 233    Strings
 234       green
 235
 236    Comments
 237       red
 238
 239    Definitions
 240       blue
 241
 242 Shell colors:
 243    Console output
 244       brown
 245
 246    stdout
 247       blue
 248
 249    stderr
 250       dark green
 251
 252    stdin
 253       black
 254
 255
 256 Startup
 257 -------
 258
 259 Upon startup with the ``-s`` option, IDLE will execute the file referenced by
 260 the environment variables :envvar:`IDLESTARTUP` or :envvar:`PYTHONSTARTUP`.
 261 Idle first checks for ``IDLESTARTUP``; if ``IDLESTARTUP`` is present the file
 262 referenced is run.  If ``IDLESTARTUP`` is not present, Idle checks for
 263 ``PYTHONSTARTUP``.  Files referenced by these environment variables are
 264 convenient places to store functions that are used frequently from the Idle
 265 shell, or for executing import statements to import common modules.
 266
 267 In addition, ``Tk`` also loads a startup file if it is present.  Note that the
 268 Tk file is loaded unconditionally.  This additional file is ``.Idle.py`` and is
 269 looked for in the user's home directory.  Statements in this file will be
 270 executed in the Tk namespace, so this file is not useful for importing functions
 271 to be used from Idle's Python shell.
 272
 273
 274 Command line usage
 275 ^^^^^^^^^^^^^^^^^^
 276
 277 ::
 278
 279    idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ...
 280
 281    -c command  run this command
 282    -d          enable debugger
 283    -e          edit mode; arguments are files to be edited
 284    -s          run $IDLESTARTUP or $PYTHONSTARTUP first
 285    -t title    set title of shell window
 286
 287 If there are arguments:
 288
 289 #. If :option:`-e` is used, arguments are files opened for editing and
 290    ``sys.argv`` reflects the arguments passed to IDLE itself.
 291
 292 #. Otherwise, if :option:`-c` is used, all arguments are placed in
 293    ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``.
 294
 295 #. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first
 296    argument is a script which is executed with the remaining arguments in
 297    ``sys.argv[1:...]``  and ``sys.argv[0]`` set to the script name.  If the script
 298    name is '-', no script is executed but an interactive Python session is started;
 299    the arguments are still available in ``sys.argv``.
 300
 301