1.. _idle: 2 3IDLE 4==== 5 6.. index:: 7 single: IDLE 8 single: Python Editor 9 single: Integrated Development Environment 10 11.. moduleauthor:: Guido van Rossum <[email protected]> 12 13IDLE is Python's Integrated Development and Learning Environment. 14 15IDLE has the following features: 16 17* coded in 100% pure Python, using the :mod:`tkinter` GUI toolkit 18 19* cross-platform: works mostly the same on Windows, Unix, and Mac OS X 20 21* Python shell window (interactive interpreter) with colorizing 22 of code input, output, and error messages 23 24* multi-window text editor with multiple undo, Python colorizing, 25 smart indent, call tips, auto completion, and other features 26 27* search within any window, replace within editor windows, and search 28 through multiple files (grep) 29 30* debugger with persistent breakpoints, stepping, and viewing 31 of global and local namespaces 32 33* configuration, browsers, and other dialogs 34 35Menus 36----- 37 38IDLE has two main window types, the Shell window and the Editor window. It is 39possible to have multiple editor windows simultaneously. Output windows, such 40as used for Edit / Find in Files, are a subtype of edit window. They currently 41have the same top menu as Editor windows but a different default title and 42context menu. 43 44IDLE's menus dynamically change based on which window is currently selected. 45Each menu documented below indicates which window type it is associated with. 46 47File menu (Shell and Editor) 48^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 49 50New File 51 Create a new file editing window. 52 53Open... 54 Open an existing file with an Open dialog. 55 56Recent Files 57 Open a list of recent files. Click one to open it. 58 59Open Module... 60 Open an existing module (searches sys.path). 61 62.. index:: 63 single: Class browser 64 single: Path browser 65 66Class Browser 67 Show functions, classes, and methods in the current Editor file in a 68 tree structure. In the shell, open a module first. 69 70Path Browser 71 Show sys.path directories, modules, functions, classes and methods in a 72 tree structure. 73 74Save 75 Save the current window to the associated file, if there is one. Windows 76 that have been changed since being opened or last saved have a \* before 77 and after the window title. If there is no associated file, 78 do Save As instead. 79 80Save As... 81 Save the current window with a Save As dialog. The file saved becomes the 82 new associated file for the window. 83 84Save Copy As... 85 Save the current window to different file without changing the associated 86 file. 87 88Print Window 89 Print the current window to the default printer. 90 91Close 92 Close the current window (ask to save if unsaved). 93 94Exit 95 Close all windows and quit IDLE (ask to save unsaved windows). 96 97Edit menu (Shell and Editor) 98^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 99 100Undo 101 Undo the last change to the current window. A maximum of 1000 changes may 102 be undone. 103 104Redo 105 Redo the last undone change to the current window. 106 107Cut 108 Copy selection into the system-wide clipboard; then delete the selection. 109 110Copy 111 Copy selection into the system-wide clipboard. 112 113Paste 114 Insert contents of the system-wide clipboard into the current window. 115 116The clipboard functions are also available in context menus. 117 118Select All 119 Select the entire contents of the current window. 120 121Find... 122 Open a search dialog with many options 123 124Find Again 125 Repeat the last search, if there is one. 126 127Find Selection 128 Search for the currently selected string, if there is one. 129 130Find in Files... 131 Open a file search dialog. Put results in a new output window. 132 133Replace... 134 Open a search-and-replace dialog. 135 136Go to Line 137 Move cursor to the line number requested and make that line visible. 138 139Show Completions 140 Open a scrollable list allowing selection of keywords and attributes. See 141 Completions in the Tips sections below. 142 143Expand Word 144 Expand a prefix you have typed to match a full word in the same window; 145 repeat to get a different expansion. 146 147Show call tip 148 After an unclosed parenthesis for a function, open a small window with 149 function parameter hints. 150 151Show surrounding parens 152 Highlight the surrounding parenthesis. 153 154Format menu (Editor window only) 155^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 156 157Indent Region 158 Shift selected lines right by the indent width (default 4 spaces). 159 160Dedent Region 161 Shift selected lines left by the indent width (default 4 spaces). 162 163Comment Out Region 164 Insert ## in front of selected lines. 165 166Uncomment Region 167 Remove leading # or ## from selected lines. 168 169Tabify Region 170 Turn *leading* stretches of spaces into tabs. (Note: We recommend using 171 4 space blocks to indent Python code.) 172 173Untabify Region 174 Turn *all* tabs into the correct number of spaces. 175 176Toggle Tabs 177 Open a dialog to switch between indenting with spaces and tabs. 178 179New Indent Width 180 Open a dialog to change indent width. The accepted default by the Python 181 community is 4 spaces. 182 183Format Paragraph 184 Reformat the current blank-line-delimited paragraph in comment block or 185 multiline string or selected line in a string. All lines in the 186 paragraph will be formatted to less than N columns, where N defaults to 72. 187 188Strip trailing whitespace 189 Remove any space characters after the last non-space character of a line. 190 191.. index:: 192 single: Run script 193 194Run menu (Editor window only) 195^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 196 197Python Shell 198 Open or wake up the Python Shell window. 199 200Check Module 201 Check the syntax of the module currently open in the Editor window. If the 202 module has not been saved IDLE will either prompt the user to save or 203 autosave, as selected in the General tab of the Idle Settings dialog. If 204 there is a syntax error, the approximate location is indicated in the 205 Editor window. 206 207Run Module 208 Do Check Module (above). If no error, restart the shell to clean the 209 environment, then execute the module. Output is displayed in the Shell 210 window. Note that output requires use of ``print`` or ``write``. 211 When execution is complete, the Shell retains focus and displays a prompt. 212 At this point, one may interactively explore the result of execution. 213 This is similar to executing a file with ``python -i file`` at a command 214 line. 215 216Shell menu (Shell window only) 217^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 218 219View Last Restart 220 Scroll the shell window to the last Shell restart. 221 222Restart Shell 223 Restart the shell to clean the environment. 224 225Interrupt Execution 226 Stop a running program. 227 228Debug menu (Shell window only) 229^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 230 231Go to File/Line 232 Look on the current line. with the cursor, and the line above for a filename 233 and line number. If found, open the file if not already open, and show the 234 line. Use this to view source lines referenced in an exception traceback 235 and lines found by Find in Files. Also available in the context menu of 236 the Shell window and Output windows. 237 238.. index:: 239 single: debugger 240 single: stack viewer 241 242Debugger (toggle) 243 When activated, code entered in the Shell or run from an Editor will run 244 under the debugger. In the Editor, breakpoints can be set with the context 245 menu. This feature is still incomplete and somewhat experimental. 246 247Stack Viewer 248 Show the stack traceback of the last exception in a tree widget, with 249 access to locals and globals. 250 251Auto-open Stack Viewer 252 Toggle automatically opening the stack viewer on an unhandled exception. 253 254Options menu (Shell and Editor) 255^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 256 257Configure IDLE 258 Open a configuration dialog and change preferences for the following: 259 fonts, indentation, keybindings, text color themes, startup windows and 260 size, additional help sources, and extensions (see below). On OS X, 261 open the configuration dialog by selecting Preferences in the application 262 menu. To use a new built-in color theme (IDLE Dark) with older IDLEs, 263 save it as a new custom theme. 264 265 Non-default user settings are saved in a .idlerc directory in the user's 266 home directory. Problems caused by bad user configuration files are solved 267 by editing or deleting one or more of the files in .idlerc. 268 269Code Context (toggle)(Editor Window only) 270 Open a pane at the top of the edit window which shows the block context 271 of the code which has scrolled above the top of the window. 272 273Window menu (Shell and Editor) 274^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 275 276Zoom Height 277 Toggles the window between normal size and maximum height. The initial size 278 defaults to 40 lines by 80 chars unless changed on the General tab of the 279 Configure IDLE dialog. 280 281The rest of this menu lists the names of all open windows; select one to bring 282it to the foreground (deiconifying it if necessary). 283 284Help menu (Shell and Editor) 285^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 286 287About IDLE 288 Display version, copyright, license, credits, and more. 289 290IDLE Help 291 Display a help file for IDLE detailing the menu options, basic editing and 292 navigation, and other tips. 293 294Python Docs 295 Access local Python documentation, if installed, or start a web browser 296 and open docs.python.org showing the latest Python documentation. 297 298Turtle Demo 299 Run the turtledemo module with example python code and turtle drawings. 300 301Additional help sources may be added here with the Configure IDLE dialog under 302the General tab. 303 304.. index:: 305 single: Cut 306 single: Copy 307 single: Paste 308 single: Set Breakpoint 309 single: Clear Breakpoint 310 single: breakpoints 311 312Context Menus 313^^^^^^^^^^^^^^^^^^^^^^^^^^ 314 315Open a context menu by right-clicking in a window (Control-click on OS X). 316Context menus have the standard clipboard functions also on the Edit menu. 317 318Cut 319 Copy selection into the system-wide clipboard; then delete the selection. 320 321Copy 322 Copy selection into the system-wide clipboard. 323 324Paste 325 Insert contents of the system-wide clipboard into the current window. 326 327Editor windows also have breakpoint functions. Lines with a breakpoint set are 328specially marked. Breakpoints only have an effect when running under the 329debugger. Breakpoints for a file are saved in the user's .idlerc directory. 330 331Set Breakpoint 332 Set a breakpoint on the current line. 333 334Clear Breakpoint 335 Clear the breakpoint on that line. 336 337Shell and Output windows have the following. 338 339Go to file/line 340 Same as in Debug menu. 341 342 343Editing and navigation 344---------------------- 345 346In this section, 'C' refers to the :kbd:`Control` key on Windows and Unix and 347the :kbd:`Command` key on Mac OSX. 348 349* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right 350 351* :kbd:`C-Backspace` delete word left; :kbd:`C-Del` delete word to the right 352 353* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around 354 355* :kbd:`C-LeftArrow` and :kbd:`C-RightArrow` moves by words 356 357* :kbd:`Home`/:kbd:`End` go to begin/end of line 358 359* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file 360 361* Some useful Emacs bindings are inherited from Tcl/Tk: 362 363 * :kbd:`C-a` beginning of line 364 365 * :kbd:`C-e` end of line 366 367 * :kbd:`C-k` kill line (but doesn't put it in clipboard) 368 369 * :kbd:`C-l` center window around the insertion point 370 371 * :kbd:`C-b` go backward one character without deleting (usually you can 372 also use the cursor key for this) 373 374 * :kbd:`C-f` go forward one character without deleting (usually you can 375 also use the cursor key for this) 376 377 * :kbd:`C-p` go up one line (usually you can also use the cursor key for 378 this) 379 380 * :kbd:`C-d` delete next character 381 382Standard keybindings (like :kbd:`C-c` to copy and :kbd:`C-v` to paste) 383may work. Keybindings are selected in the Configure IDLE dialog. 384 385 386Automatic indentation 387^^^^^^^^^^^^^^^^^^^^^ 388 389After a block-opening statement, the next line is indented by 4 spaces (in the 390Python Shell window by one tab). After certain keywords (break, return etc.) 391the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up 392to 4 spaces if they are there. :kbd:`Tab` inserts spaces (in the Python 393Shell window one tab), number depends on Indent width. Currently, tabs 394are restricted to four spaces due to Tcl/Tk limitations. 395 396See also the indent/dedent region commands in the edit menu. 397 398Completions 399^^^^^^^^^^^ 400 401Completions are supplied for functions, classes, and attributes of classes, 402both built-in and user-defined. Completions are also provided for 403filenames. 404 405The AutoCompleteWindow (ACW) will open after a predefined delay (default is 406two seconds) after a '.' or (in a string) an os.sep is typed. If after one 407of those characters (plus zero or more other characters) a tab is typed 408the ACW will open immediately if a possible continuation is found. 409 410If there is only one possible completion for the characters entered, a 411:kbd:`Tab` will supply that completion without opening the ACW. 412 413'Show Completions' will force open a completions window, by default the 414:kbd:`C-space` will open a completions window. In an empty 415string, this will contain the files in the current directory. On a 416blank line, it will contain the built-in and user-defined functions and 417classes in the current namespaces, plus any modules imported. If some 418characters have been entered, the ACW will attempt to be more specific. 419 420If a string of characters is typed, the ACW selection will jump to the 421entry most closely matching those characters. Entering a :kbd:`tab` will 422cause the longest non-ambiguous match to be entered in the Editor window or 423Shell. Two :kbd:`tab` in a row will supply the current ACW selection, as 424will return or a double click. Cursor keys, Page Up/Down, mouse selection, 425and the scroll wheel all operate on the ACW. 426 427"Hidden" attributes can be accessed by typing the beginning of hidden 428name after a '.', e.g. '_'. This allows access to modules with 429``__all__`` set, or to class-private attributes. 430 431Completions and the 'Expand Word' facility can save a lot of typing! 432 433Completions are currently limited to those in the namespaces. Names in 434an Editor window which are not via ``__main__`` and :data:`sys.modules` will 435not be found. Run the module once with your imports to correct this situation. 436Note that IDLE itself places quite a few modules in sys.modules, so 437much can be found by default, e.g. the re module. 438 439If you don't like the ACW popping up unbidden, simply make the delay 440longer or disable the extension. 441 442Calltips 443^^^^^^^^ 444 445A calltip is shown when one types :kbd:`(` after the name of an *accessible* 446function. A name expression may include dots and subscripts. A calltip 447remains until it is clicked, the cursor is moved out of the argument area, 448or :kbd:`)` is typed. When the cursor is in the argument part of a definition, 449the menu or shortcut display a calltip. 450 451A calltip consists of the function signature and the first line of the 452docstring. For builtins without an accessible signature, the calltip 453consists of all lines up the fifth line or the first blank line. These 454details may change. 455 456The set of *accessible* functions depends on what modules have been imported 457into the user process, including those imported by Idle itself, 458and what definitions have been run, all since the last restart. 459 460For example, restart the Shell and enter ``itertools.count(``. A calltip 461appears because Idle imports itertools into the user process for its own use. 462(This could change.) Enter ``turtle.write(`` and nothing appears. Idle does 463not import turtle. The menu or shortcut do nothing either. Enter 464``import turtle`` and then ``turtle.write(`` will work. 465 466In an editor, import statements have no effect until one runs the file. One 467might want to run a file after writing the import statements at the top, 468or immediately run an existing file before editing. 469 470Python Shell window 471^^^^^^^^^^^^^^^^^^^ 472 473* :kbd:`C-c` interrupts executing command 474 475* :kbd:`C-d` sends end-of-file; closes window if typed at a ``>>>`` prompt 476 477* :kbd:`Alt-/` (Expand word) is also useful to reduce typing 478 479 Command history 480 481 * :kbd:`Alt-p` retrieves previous command matching what you have typed. On 482 OS X use :kbd:`C-p`. 483 484 * :kbd:`Alt-n` retrieves next. On OS X use :kbd:`C-n`. 485 486 * :kbd:`Return` while on any previous command retrieves that command 487 488 489Text colors 490^^^^^^^^^^^ 491 492Idle defaults to black on white text, but colors text with special meanings. 493For the shell, these are shell output, shell error, user output, and 494user error. For Python code, at the shell prompt or in an editor, these are 495keywords, builtin class and function names, names following ``class`` and 496``def``, strings, and comments. For any text window, these are the cursor (when 497present), found text (when possible), and selected text. 498 499Text coloring is done in the background, so uncolorized text is occasionally 500visible. To change the color scheme, use the Configure IDLE dialog 501Highlighting tab. The marking of debugger breakpoint lines in the editor and 502text in popups and dialogs is not user-configurable. 503 504 505Startup and code execution 506-------------------------- 507 508Upon startup with the ``-s`` option, IDLE will execute the file referenced by 509the environment variables :envvar:`IDLESTARTUP` or :envvar:`PYTHONSTARTUP`. 510IDLE first checks for ``IDLESTARTUP``; if ``IDLESTARTUP`` is present the file 511referenced is run. If ``IDLESTARTUP`` is not present, IDLE checks for 512``PYTHONSTARTUP``. Files referenced by these environment variables are 513convenient places to store functions that are used frequently from the IDLE 514shell, or for executing import statements to import common modules. 515 516In addition, ``Tk`` also loads a startup file if it is present. Note that the 517Tk file is loaded unconditionally. This additional file is ``.Idle.py`` and is 518looked for in the user's home directory. Statements in this file will be 519executed in the Tk namespace, so this file is not useful for importing 520functions to be used from IDLE's Python shell. 521 522 523Command line usage 524^^^^^^^^^^^^^^^^^^ 525 526.. code-block:: none 527 528 idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ... 529 530 -c command run command in the shell window 531 -d enable debugger and open shell window 532 -e open editor window 533 -h print help message with legal combinations and exit 534 -i open shell window 535 -r file run file in shell window 536 -s run $IDLESTARTUP or $PYTHONSTARTUP first, in shell window 537 -t title set title of shell window 538 - run stdin in shell (- must be last option before args) 539 540If there are arguments: 541 542* If ``-``, ``-c``, or ``r`` is used, all arguments are placed in 543 ``sys.argv[1:...]`` and ``sys.argv[0]`` is set to ``''``, ``'-c'``, 544 or ``'-r'``. No editor window is opened, even if that is the default 545 set in the Options dialog. 546 547* Otherwise, arguments are files opened for editing and 548 ``sys.argv`` reflects the arguments passed to IDLE itself. 549 550 551IDLE-console differences 552^^^^^^^^^^^^^^^^^^^^^^^^ 553 554As much as possible, the result of executing Python code with IDLE is the 555same as executing the same code in a console window. However, the different 556interface and operation occasionally affect visible results. For instance, 557``sys.modules`` starts with more entries. 558 559IDLE also replaces ``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` with 560objects that get input from and send output to the Shell window. 561When this window has the focus, it controls the keyboard and screen. 562This is normally transparent, but functions that directly access the keyboard 563and screen will not work. If ``sys`` is reset with ``reload(sys)``, 564IDLE's changes are lost and things like ``input``, ``raw_input``, and 565``print`` will not work correctly. 566 567With IDLE's Shell, one enters, edits, and recalls complete statements. 568Some consoles only work with a single physical line at a time. IDLE uses 569``exec`` to run each statement. As a result, ``'__builtins__'`` is always 570defined for each statement. 571 572Running without a subprocess 573^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 574 575By default, IDLE executes user code in a separate subprocess via a socket, 576which uses the internal loopback interface. This connection is not 577externally visible and no data is sent to or received from the Internet. 578If firewall software complains anyway, you can ignore it. 579 580If the attempt to make the socket connection fails, Idle will notify you. 581Such failures are sometimes transient, but if persistent, the problem 582may be either a firewall blocking the connection or misconfiguration of 583a particular system. Until the problem is fixed, one can run Idle with 584the -n command line switch. 585 586If IDLE is started with the -n command line switch it will run in a 587single process and will not create the subprocess which runs the RPC 588Python execution server. This can be useful if Python cannot create 589the subprocess or the RPC socket interface on your platform. However, 590in this mode user code is not isolated from IDLE itself. Also, the 591environment is not restarted when Run/Run Module (F5) is selected. If 592your code has been modified, you must reload() the affected modules and 593re-import any specific items (e.g. from foo import baz) if the changes 594are to take effect. For these reasons, it is preferable to run IDLE 595with the default subprocess if at all possible. 596 597.. deprecated:: 3.4 598 599 600Help and preferences 601-------------------- 602 603Additional help sources 604^^^^^^^^^^^^^^^^^^^^^^^ 605 606IDLE includes a help menu entry called "Python Docs" that will open the 607extensive sources of help, including tutorials, available at docs.python.org. 608Selected URLs can be added or removed from the help menu at any time using the 609Configure IDLE dialog. See the IDLE help option in the help menu of IDLE for 610more information. 611 612 613Setting preferences 614^^^^^^^^^^^^^^^^^^^ 615 616The font preferences, highlighting, keys, and general preferences can be 617changed via Configure IDLE on the Option menu. Keys can be user defined; 618IDLE ships with four built-in key sets. In addition, a user can create a 619custom key set in the Configure IDLE dialog under the keys tab. 620 621 622Extensions 623^^^^^^^^^^ 624 625IDLE contains an extension facility. Preferences for extensions can be 626changed with Configure Extensions. See the beginning of config-extensions.def 627in the idlelib directory for further information. The default extensions 628are currently: 629 630* FormatParagraph 631 632* AutoExpand 633 634* ZoomHeight 635 636* ScriptBinding 637 638* CallTips 639 640* ParenMatch 641 642* AutoComplete 643 644* CodeContext 645 646* RstripExtension 647