- -
-

IDLE¶

-

Source code: Lib/idlelib/

-
-

IDLE is Python’s Integrated Development and Learning Environment.

-

IDLE has the following features:

-
    -
  • coded in 100% pure Python, using the tkinter GUI toolkit
    • -
  • cross-platform: works mostly the same on Windows, Unix, and macOS
    • -
  • Python shell window (interactive interpreter) with colorizing -of code input, output, and error messages
    • -
  • multi-window text editor with multiple undo, Python colorizing, -smart indent, call tips, auto completion, and other features
    • -
  • search within any window, replace within editor windows, and search -through multiple files (grep)
    • -
  • debugger with persistent breakpoints, stepping, and viewing -of global and local namespaces
    • -
  • configuration, browsers, and other dialogs
    • -
- -
-

Editing and navigation¶

-
-

Editor windows¶

-

IDLE may open editor windows when it starts, depending on settings -and how you start IDLE. Thereafter, use the File menu. There can be only -one open editor window for a given file.

-

The title bar contains the name of the file, the full path, and the version -of Python and IDLE running the window. The status bar contains the line -number (‘Ln’) and column number (‘Col’). Line numbers start with 1; -column numbers with 0.

-

IDLE assumes that files with a known .py* extension contain Python code -and that other files do not. Run Python code with the Run menu.

-
-
-

Key bindings¶

-

In this section, ‘C’ refers to the Control key on Windows and Unix and -the Command key on macOS.

-
    -

  • Backspace deletes to the left; Del deletes to the right

    -
    • -

  • C-Backspace delete word left; C-Del delete word to the right

    -
    • -

  • Arrow keys and Page Up/Page Down to move around

    -
    • -

  • C-LeftArrow and C-RightArrow moves by words

    -
    • -

  • Home/End go to begin/end of line

    -
    • -

  • C-Home/C-End go to begin/end of file

    -
    • -

  • Some useful Emacs bindings are inherited from Tcl/Tk:

    -
    -
      -
    • C-a beginning of line
      • -
    • C-e end of line
      • -
    • C-k kill line (but doesn’t put it in clipboard)
      • -
    • C-l center window around the insertion point
      • -
    • C-b go backward one character without deleting (usually you can -also use the cursor key for this)
      • -
    • C-f go forward one character without deleting (usually you can -also use the cursor key for this)
      • -
    • C-p go up one line (usually you can also use the cursor key for -this)
      • -
    • C-d delete next character
      • -
    -
    -
    • -
-

Standard keybindings (like C-c to copy and C-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. 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 -Tab will supply that completion without opening the ACW.

-

‘Show Completions’ will force open a completions window, by default the -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 namespaces, 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 tab will -cause the longest non-ambiguous match to be entered in the Editor window or -Shell. Two 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 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.

-
-
-

Calltips¶

-

A calltip is shown when one types ( after the name of an accessible -function. A name expression may include dots and subscripts. A calltip -remains until it is clicked, the cursor is moved out of the argument area, -or ) is typed. When the cursor is in the argument part of a definition, -the menu or shortcut display a calltip.

-

A calltip consists of the function signature and the first line of the -docstring. For builtins without an accessible signature, the calltip -consists of all lines up the fifth line or the first blank line. These -details may change.

-

The set of accessible functions depends on what modules have been imported -into the user process, including those imported by Idle itself, -and what definitions have been run, all since the last restart.

-

For example, restart the Shell and enter itertools.count(. A calltip -appears because Idle imports itertools into the user process for its own use. -(This could change.) Enter turtle.write( and nothing appears. Idle does -not import turtle. The menu or shortcut do nothing either. Enter -import turtle and then turtle.write( will work.

-

In an editor, import statements have no effect until one runs the file. One -might want to run a file after writing the import statements at the top, -or immediately run an existing file before editing.

-
-
-

Python Shell window¶

-

With IDLE’s Shell, one enters, edits, and recalls complete statements. -Most consoles and terminals only work with a single physical line at a time.

-

When one pastes code into Shell, it is not compiled and possibly executed -until one hits Return. One may edit pasted code first. -If one pastes more that one statement into Shell, the result will be a -SyntaxError when multiple statements are compiled as if they were one.

-

The editing features described in previous subsections work when entering -code interactively. IDLE’s Shell window also responds to the following keys.

-
    -

  • C-c interrupts executing command

    -
    • -

  • C-d sends end-of-file; closes window if typed at a >>> prompt

    -
    • -

  • Alt-/ (Expand word) is also useful to reduce typing

    -

    Command history

    -
      -
    • Alt-p retrieves previous command matching what you have typed. On -macOS use C-p.
      • -
    • Alt-n retrieves next. On macOS use C-n.
      • -
    • Return while on any previous command retrieves that command
      • -
    -
    • -
-
-
-

Text colors¶

-

Idle defaults to black on white text, but colors text with special meanings. -For the shell, these are shell output, shell error, user output, and -user error. For Python code, at the shell prompt or in an editor, these are -keywords, builtin class and function names, names following class and -def, strings, and comments. For any text window, these are the cursor (when -present), found text (when possible), and selected text.

-

Text coloring is done in the background, so uncolorized text is occasionally -visible. To change the color scheme, use the Configure IDLE dialog -Highlighting tab. The marking of debugger breakpoint lines in the editor and -text in popups and dialogs is not user-configurable.

-
-
-
-

Startup and code execution¶

-

Upon startup with the -s option, IDLE will execute the file referenced by -the environment variables IDLESTARTUP or PYTHONSTARTUP. -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 -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.

-
-

Command line usage¶

-
idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ...
-
--c command  run command in the shell window
--d          enable debugger and open shell window
--e          open editor window
--h          print help message with legal combinations and exit
--i          open shell window
--r file     run file in shell window
--s          run $IDLESTARTUP or $PYTHONSTARTUP first, in shell window
--t title    set title of shell window
--           run stdin in shell (- must be last option before args)
-
-
-

If there are arguments:

-
    -
  • If -, -c, or r is used, all arguments are placed in -sys.argv[1:...] and sys.argv[0] is set to '', '-c', -or '-r'. No editor window is opened, even if that is the default -set in the Options dialog.
    • -
  • Otherwise, arguments are files opened for editing and -sys.argv reflects the arguments passed to IDLE itself.
    • -
-
-
-

Startup failure¶

-

IDLE uses a socket to communicate between the IDLE GUI process and the user -code execution process. A connection must be established whenever the Shell -starts or restarts. (The latter is indicated by a divider line that says -‘RESTART’). If the user process fails to connect to the GUI process, it -displays a Tk error box with a ‘cannot connect’ message that directs the -user here. It then exits.

-

A common cause of failure is a user-written file with the same name as a -standard library module, such as random.py and tkinter.py. When such a -file is located in the same directory as a file that is about to be run, -IDLE cannot import the stdlib file. The current fix is to rename the -user file.

-

Though less common than in the past, an antivirus or firewall program may -stop the connection. If the program cannot be taught to allow the -connection, then it must be turned off for IDLE to work. It is safe to -allow this internal connection because no data is visible on external -ports. A similar problem is a network mis-configuration that blocks -connections.

-

Python installation issues occasionally stop IDLE: multiple versions can -clash, or a single installation might need admin access. If one undo the -clash, or cannot or does not want to run as admin, it might be easiest to -completely remove Python and start over.

-

A zombie pythonw.exe process could be a problem. On Windows, use Task -Manager to detect and stop one. Sometimes a restart initiated by a program -crash or Keyboard Interrupt (control-C) may fail to connect. Dismissing -the error box or Restart Shell on the Shell menu may fix a temporary problem.

-

When IDLE first starts, it attempts to read user configuration files in -~/.idlerc/ (~ is one’s home directory). If there is a problem, an error -message should be displayed. Leaving aside random disk glitches, this can -be prevented by never editing the files by hand, using the configuration -dialog, under Options, instead Options. Once it happens, the solution may -be to delete one or more of the configuration files.

-

If IDLE quits with no message, and it was not started from a console, try -starting from a console (python -m idlelib) and see if a message appears.

-
-
-

Running user code¶

-

With rare exceptions, the result of executing Python code with IDLE is -intended to be the same as executing the same code by the default method, -directly with Python in a text-mode system console or terminal window. -However, the different interface and operation occasionally affect -visible results. For instance, sys.modules starts with more entries, -and threading.activeCount() returns 2 instead of 1.

-

By default, IDLE runs user code in a separate OS process rather than in -the user interface process that runs the shell and editor. In the execution -process, it replaces sys.stdin, sys.stdout, and sys.stderr -with objects that get input from and send output to the Shell window. -The original values stored in sys.__stdin__, sys.__stdout__, and -sys.__stderr__ are not touched, but may be None.

-

When Shell has the focus, it controls the keyboard and screen. This is -normally transparent, but functions that directly access the keyboard -and screen will not work. These include system-specific functions that -determine whether a key has been pressed and if so, which.

-

IDLE’s standard stream replacements are not inherited by subprocesses -created in the execution process, whether directly by user code or by modules -such as multiprocessing. If such subprocess use input from sys.stdin -or print or write to sys.stdout or sys.stderr, -IDLE should be started in a command line window. The secondary subprocess -will then be attached to that window for input and output.

-

If sys is reset by user code, such as with importlib.reload(sys), -IDLE’s changes are lost and input from the keyboard and output to the screen -will not work correctly.

-
-
-

User output in Shell¶

-

When a program outputs text, the result is determined by the -corresponding output device. When IDLE executes user code, sys.stdout -and sys.stderr are connected to the display area of IDLE’s Shell. Some of -its features are inherited from the underlying Tk Text widget. Others -are programmed additions. Where it matters, Shell is designed for development -rather than production runs.

-

For instance, Shell never throws away output. A program that sends unlimited -output to Shell will eventually fill memory, resulting in a memory error. -In contrast, some system text windows only keep the last n lines of output. -A Windows console, for instance, keeps a user-settable 1 to 9999 lines, -with 300 the default.

-

Text widgets display a subset of Unicode, the Basic Multilingual Plane (BMP). -Which characters get a proper glyph instead of a replacement box depends on -the operating system and installed fonts. Newline characters cause following -text to appear on a new line, but other control characters are either -replaced with a box or deleted. However, repr(), which is used for -interactive echo of expression values, replaces control characters, -some BMP codepoints, and all non-BMP characters with escape codes -before they are output.

-

Normal and error output are generally kept separate (on separate lines) -from code input and each other. They each get different highlight colors.

-

For SyntaxError tracebacks, the normal ‘^’ marking where the error was -detected is replaced by coloring the text with an error highlight. -When code run from a file causes other exceptions, one may right click -on a traceback line to jump to the corresponding line in an IDLE editor. -The file will be opened if necessary.

-

Shell has a special facility for squeezing output lines down to a -‘Squeezed text’ label. This is done automatically -for output over N lines (N = 50 by default). -N can be changed in the PyShell section of the General -page of the Settings dialog. Output with fewer lines can be squeezed by -right clicking on the output. This can be useful lines long enough to slow -down scrolling.

-

Squeezed output is expanded in place by double-clicking the label. -It can also be sent to the clipboard or a separate view window by -right-clicking the label.

-
-
-

Developing tkinter applications¶

-

IDLE is intentionally different from standard Python in order to -facilitate development of tkinter programs. Enter import tkinter as tk; -root = tk.Tk() in standard Python and nothing appears. Enter the same -in IDLE and a tk window appears. In standard Python, one must also enter -root.update() to see the window. IDLE does the equivalent in the -background, about 20 times a second, which is about every 50 milleseconds. -Next enter b = tk.Button(root, text='button'); b.pack(). Again, -nothing visibly changes in standard Python until one enters root.update().

-

Most tkinter programs run root.mainloop(), which usually does not -return until the tk app is destroyed. If the program is run with -python -i or from an IDLE editor, a >>> shell prompt does not -appear until mainloop() returns, at which time there is nothing left -to interact with.

-

When running a tkinter program from an IDLE editor, one can comment out -the mainloop call. One then gets a shell prompt immediately and can -interact with the live application. One just has to remember to -re-enable the mainloop call when running in standard Python.

-
-
-

Running without a subprocess¶

-

By default, IDLE executes user code in a separate subprocess via a socket, -which uses the internal loopback interface. This connection is not -externally visible and no data is sent to or received from the Internet. -If firewall software complains anyway, you can ignore it.

-

If the attempt to make the socket connection fails, Idle will notify you. -Such failures are sometimes transient, but if persistent, the problem -may be either a firewall blocking the connection or misconfiguration of -a particular system. Until the problem is fixed, one can run Idle with -the -n command line switch.

-

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.

-
-

Deprecated since version 3.4.

-
-
-
-
-

Help and preferences¶

-
-

Help sources¶

-

Help menu entry “IDLE Help†displays a formatted html version of the -IDLE chapter of the Library Reference. The result, in a read-only -tkinter text window, is close to what one sees in a web browser. -Navigate through the text with a mousewheel, -the scrollbar, or up and down arrow keys held down. -Or click the TOC (Table of Contents) button and select a section -header in the opened box.

-

Help menu entry “Python Docs†opens the extensive sources of help, -including tutorials, available at docs.python.org/x.y, where ‘x.y’ -is the currently running Python version. If your system -has an off-line copy of the docs (this may be an installation option), -that will be opened instead.

-

Selected URLs can be added or removed from the help menu at any time using the -General tab of the Configure IDLE dialog .

-
-
-

Setting preferences¶

-

The font preferences, highlighting, keys, and general preferences can be -changed via Configure IDLE on the Option menu. 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.

-
-
-

IDLE on macOS¶

-

Under System Preferences: Dock, one can set “Prefer tabs when opening -documents†to “Alwaysâ€. This setting is not compatible with the tk/tkinter -GUI framework used by IDLE, and it breaks a few IDLE features.

-
-
-

Extensions¶

-

IDLE contains an extension facility. Preferences for extensions can be -changed with the Extensions tab of the preferences dialog. See the -beginning of config-extensions.def in the idlelib directory for further -information. The only current default extension is zzdummy, an example -also used for testing.

-
-
-
- - -