IDLE¶
jpayne@68:Source code: Lib/idlelib/
jpayne@68:jpayne@68:
IDLE is Python’s Integrated Development and Learning Environment.
jpayne@68:IDLE has the following features:
jpayne@68:-
jpayne@68:
coded in 100% pure Python, using the
tkinterGUI toolkit
jpayne@68: cross-platform: works mostly the same on Windows, Unix, and macOS
jpayne@68: Python shell window (interactive interpreter) with colorizing jpayne@68: of code input, output, and error messages
jpayne@68: multi-window text editor with multiple undo, Python colorizing, jpayne@68: smart indent, call tips, auto completion, and other features
jpayne@68: search within any window, replace within editor windows, and search jpayne@68: through multiple files (grep)
jpayne@68: debugger with persistent breakpoints, stepping, and viewing jpayne@68: of global and local namespaces
jpayne@68: configuration, browsers, and other dialogs
jpayne@68:
Startup and code execution¶
jpayne@68:Upon startup with the -s option, IDLE will execute the file referenced by
jpayne@68: the environment variables IDLESTARTUP or PYTHONSTARTUP.
jpayne@68: IDLE first checks for IDLESTARTUP; if IDLESTARTUP is present the file
jpayne@68: referenced is run. If IDLESTARTUP is not present, IDLE checks for
jpayne@68: PYTHONSTARTUP. Files referenced by these environment variables are
jpayne@68: convenient places to store functions that are used frequently from the IDLE
jpayne@68: 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
jpayne@68: Tk file is loaded unconditionally. This additional file is .Idle.py and is
jpayne@68: looked for in the user’s home directory. Statements in this file will be
jpayne@68: executed in the Tk namespace, so this file is not useful for importing
jpayne@68: functions to be used from IDLE’s Python shell.
Command line usage¶
jpayne@68:idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ...
jpayne@68:
jpayne@68: -c command run command in the shell window
jpayne@68: -d enable debugger and open shell window
jpayne@68: -e open editor window
jpayne@68: -h print help message with legal combinations and exit
jpayne@68: -i open shell window
jpayne@68: -r file run file in shell window
jpayne@68: -s run $IDLESTARTUP or $PYTHONSTARTUP first, in shell window
jpayne@68: -t title set title of shell window
jpayne@68: - run stdin in shell (- must be last option before args)
jpayne@68: If there are arguments:
jpayne@68:-
jpayne@68:
If
-,-c, orris used, all arguments are placed in jpayne@68:sys.argv[1:...]andsys.argv[0]is set to'','-c', jpayne@68: or'-r'. No editor window is opened, even if that is the default jpayne@68: set in the Options dialog.
jpayne@68: Otherwise, arguments are files opened for editing and jpayne@68:
sys.argvreflects the arguments passed to IDLE itself.
jpayne@68:
Startup failure¶
jpayne@68:IDLE uses a socket to communicate between the IDLE GUI process and the user
jpayne@68: code execution process. A connection must be established whenever the Shell
jpayne@68: starts or restarts. (The latter is indicated by a divider line that says
jpayne@68: ‘RESTART’). If the user process fails to connect to the GUI process, it
jpayne@68: displays a Tk error box with a ‘cannot connect’ message that directs the
jpayne@68: user here. It then exits.
A common cause of failure is a user-written file with the same name as a jpayne@68: standard library module, such as random.py and tkinter.py. When such a jpayne@68: file is located in the same directory as a file that is about to be run, jpayne@68: IDLE cannot import the stdlib file. The current fix is to rename the jpayne@68: user file.
jpayne@68:Though less common than in the past, an antivirus or firewall program may jpayne@68: stop the connection. If the program cannot be taught to allow the jpayne@68: connection, then it must be turned off for IDLE to work. It is safe to jpayne@68: allow this internal connection because no data is visible on external jpayne@68: ports. A similar problem is a network mis-configuration that blocks jpayne@68: connections.
jpayne@68:Python installation issues occasionally stop IDLE: multiple versions can jpayne@68: clash, or a single installation might need admin access. If one undo the jpayne@68: clash, or cannot or does not want to run as admin, it might be easiest to jpayne@68: completely remove Python and start over.
jpayne@68:A zombie pythonw.exe process could be a problem. On Windows, use Task jpayne@68: Manager to detect and stop one. Sometimes a restart initiated by a program jpayne@68: crash or Keyboard Interrupt (control-C) may fail to connect. Dismissing jpayne@68: the error box or Restart Shell on the Shell menu may fix a temporary problem.
jpayne@68:When IDLE first starts, it attempts to read user configuration files in jpayne@68: ~/.idlerc/ (~ is one’s home directory). If there is a problem, an error jpayne@68: message should be displayed. Leaving aside random disk glitches, this can jpayne@68: be prevented by never editing the files by hand, using the configuration jpayne@68: dialog, under Options, instead Options. Once it happens, the solution may jpayne@68: be to delete one or more of the configuration files.
jpayne@68:If IDLE quits with no message, and it was not started from a console, try
jpayne@68: starting from a console (python -m idlelib) and see if a message appears.
Running user code¶
jpayne@68:With rare exceptions, the result of executing Python code with IDLE is
jpayne@68: intended to be the same as executing the same code by the default method,
jpayne@68: directly with Python in a text-mode system console or terminal window.
jpayne@68: However, the different interface and operation occasionally affect
jpayne@68: visible results. For instance, sys.modules starts with more entries,
jpayne@68: and threading.activeCount() returns 2 instead of 1.
By default, IDLE runs user code in a separate OS process rather than in
jpayne@68: the user interface process that runs the shell and editor. In the execution
jpayne@68: process, it replaces sys.stdin, sys.stdout, and sys.stderr
jpayne@68: with objects that get input from and send output to the Shell window.
jpayne@68: The original values stored in sys.__stdin__, sys.__stdout__, and
jpayne@68: sys.__stderr__ are not touched, but may be None.
When Shell has the focus, it controls the keyboard and screen. This is jpayne@68: normally transparent, but functions that directly access the keyboard jpayne@68: and screen will not work. These include system-specific functions that jpayne@68: determine whether a key has been pressed and if so, which.
jpayne@68:IDLE’s standard stream replacements are not inherited by subprocesses
jpayne@68: created in the execution process, whether directly by user code or by modules
jpayne@68: such as multiprocessing. If such subprocess use input from sys.stdin
jpayne@68: or print or write to sys.stdout or sys.stderr,
jpayne@68: IDLE should be started in a command line window. The secondary subprocess
jpayne@68: will then be attached to that window for input and output.
The IDLE code running in the execution process adds frames to the call stack
jpayne@68: that would not be there otherwise. IDLE wraps sys.getrecursionlimit and
jpayne@68: sys.setrecursionlimit to reduce the effect of the additional stack frames.
If sys is reset by user code, such as with importlib.reload(sys),
jpayne@68: IDLE’s changes are lost and input from the keyboard and output to the screen
jpayne@68: will not work correctly.
When user code raises SystemExit either directly or by calling sys.exit, IDLE jpayne@68: returns to a Shell prompt instead of exiting.
jpayne@68:User output in Shell¶
jpayne@68:When a program outputs text, the result is determined by the
jpayne@68: corresponding output device. When IDLE executes user code, sys.stdout
jpayne@68: and sys.stderr are connected to the display area of IDLE’s Shell. Some of
jpayne@68: its features are inherited from the underlying Tk Text widget. Others
jpayne@68: are programmed additions. Where it matters, Shell is designed for development
jpayne@68: rather than production runs.
For instance, Shell never throws away output. A program that sends unlimited jpayne@68: output to Shell will eventually fill memory, resulting in a memory error. jpayne@68: In contrast, some system text windows only keep the last n lines of output. jpayne@68: A Windows console, for instance, keeps a user-settable 1 to 9999 lines, jpayne@68: with 300 the default.
jpayne@68:A Tk Text widget, and hence IDLE’s Shell, displays characters (codepoints) in jpayne@68: the BMP (Basic Multilingual Plane) subset of Unicode. Which characters are jpayne@68: displayed with a proper glyph and which with a replacement box depends on the jpayne@68: operating system and installed fonts. Tab characters cause the following text jpayne@68: to begin after the next tab stop. (They occur every 8 ‘characters’). Newline jpayne@68: characters cause following text to appear on a new line. Other control jpayne@68: characters are ignored or displayed as a space, box, or something else, jpayne@68: depending on the operating system and font. (Moving the text cursor through jpayne@68: such output with arrow keys may exhibit some surprising spacing behavior.)
jpayne@68:>>> s = 'a\tb\a<\x02><\r>\bc\nd' # Enter 22 chars.
jpayne@68: >>> len(s)
jpayne@68: 14
jpayne@68: >>> s # Display repr(s)
jpayne@68: 'a\tb\x07<\x02><\r>\x08c\nd'
jpayne@68: >>> print(s, end='') # Display s as is.
jpayne@68: # Result varies by OS and font. Try it.
jpayne@68: The repr function is used for interactive echo of expression
jpayne@68: values. It returns an altered version of the input string in which
jpayne@68: control codes, some BMP codepoints, and all non-BMP codepoints are
jpayne@68: replaced with escape codes. As demonstrated above, it allows one to
jpayne@68: identify the characters in a string, regardless of how they are displayed.
Normal and error output are generally kept separate (on separate lines) jpayne@68: from code input and each other. They each get different highlight colors.
jpayne@68:For SyntaxError tracebacks, the normal ‘^’ marking where the error was jpayne@68: detected is replaced by coloring the text with an error highlight. jpayne@68: When code run from a file causes other exceptions, one may right click jpayne@68: on a traceback line to jump to the corresponding line in an IDLE editor. jpayne@68: The file will be opened if necessary.
jpayne@68:Shell has a special facility for squeezing output lines down to a jpayne@68: ‘Squeezed text’ label. This is done automatically jpayne@68: for output over N lines (N = 50 by default). jpayne@68: N can be changed in the PyShell section of the General jpayne@68: page of the Settings dialog. Output with fewer lines can be squeezed by jpayne@68: right clicking on the output. This can be useful lines long enough to slow jpayne@68: down scrolling.
jpayne@68:Squeezed output is expanded in place by double-clicking the label. jpayne@68: It can also be sent to the clipboard or a separate view window by jpayne@68: right-clicking the label.
jpayne@68:Developing tkinter applications¶
jpayne@68:IDLE is intentionally different from standard Python in order to
jpayne@68: facilitate development of tkinter programs. Enter import tkinter as tk;
jpayne@68: root = tk.Tk() in standard Python and nothing appears. Enter the same
jpayne@68: in IDLE and a tk window appears. In standard Python, one must also enter
jpayne@68: root.update() to see the window. IDLE does the equivalent in the
jpayne@68: background, about 20 times a second, which is about every 50 milliseconds.
jpayne@68: Next enter b = tk.Button(root, text='button'); b.pack(). Again,
jpayne@68: nothing visibly changes in standard Python until one enters root.update().
Most tkinter programs run root.mainloop(), which usually does not
jpayne@68: return until the tk app is destroyed. If the program is run with
jpayne@68: python -i or from an IDLE editor, a >>> shell prompt does not
jpayne@68: appear until mainloop() returns, at which time there is nothing left
jpayne@68: to interact with.
When running a tkinter program from an IDLE editor, one can comment out jpayne@68: the mainloop call. One then gets a shell prompt immediately and can jpayne@68: interact with the live application. One just has to remember to jpayne@68: re-enable the mainloop call when running in standard Python.
jpayne@68:Running without a subprocess¶
jpayne@68:By default, IDLE executes user code in a separate subprocess via a socket, jpayne@68: which uses the internal loopback interface. This connection is not jpayne@68: externally visible and no data is sent to or received from the Internet. jpayne@68: If firewall software complains anyway, you can ignore it.
jpayne@68:If the attempt to make the socket connection fails, Idle will notify you. jpayne@68: Such failures are sometimes transient, but if persistent, the problem jpayne@68: may be either a firewall blocking the connection or misconfiguration of jpayne@68: a particular system. Until the problem is fixed, one can run Idle with jpayne@68: the -n command line switch.
jpayne@68:If IDLE is started with the -n command line switch it will run in a jpayne@68: single process and will not create the subprocess which runs the RPC jpayne@68: Python execution server. This can be useful if Python cannot create jpayne@68: the subprocess or the RPC socket interface on your platform. However, jpayne@68: in this mode user code is not isolated from IDLE itself. Also, the jpayne@68: environment is not restarted when Run/Run Module (F5) is selected. If jpayne@68: your code has been modified, you must reload() the affected modules and jpayne@68: re-import any specific items (e.g. from foo import baz) if the changes jpayne@68: are to take effect. For these reasons, it is preferable to run IDLE jpayne@68: with the default subprocess if at all possible.
jpayne@68:Deprecated since version 3.4.
jpayne@68:Help and preferences¶
jpayne@68:Help sources¶
jpayne@68:Help menu entry “IDLE Help” displays a formatted html version of the jpayne@68: IDLE chapter of the Library Reference. The result, in a read-only jpayne@68: tkinter text window, is close to what one sees in a web browser. jpayne@68: Navigate through the text with a mousewheel, jpayne@68: the scrollbar, or up and down arrow keys held down. jpayne@68: Or click the TOC (Table of Contents) button and select a section jpayne@68: header in the opened box.
jpayne@68:Help menu entry “Python Docs” opens the extensive sources of help, jpayne@68: including tutorials, available at docs.python.org/x.y, where ‘x.y’ jpayne@68: is the currently running Python version. If your system jpayne@68: has an off-line copy of the docs (this may be an installation option), jpayne@68: that will be opened instead.
jpayne@68:Selected URLs can be added or removed from the help menu at any time using the jpayne@68: General tab of the Configure IDLE dialog .
jpayne@68:Setting preferences¶
jpayne@68:The font preferences, highlighting, keys, and general preferences can be jpayne@68: changed via Configure IDLE on the Option menu. jpayne@68: Non-default user settings are saved in a .idlerc directory in the user’s jpayne@68: home directory. Problems caused by bad user configuration files are solved jpayne@68: by editing or deleting one or more of the files in .idlerc.
jpayne@68:On the Font tab, see the text sample for the effect of font face and size jpayne@68: on multiple characters in multiple languages. Edit the sample to add jpayne@68: other characters of personal interest. Use the sample to select jpayne@68: monospaced fonts. If particular characters have problems in Shell or an jpayne@68: editor, add them to the top of the sample and try changing first size jpayne@68: and then font.
jpayne@68:On the Highlights and Keys tab, select a built-in or custom color theme jpayne@68: and key set. To use a newer built-in color theme or key set with older jpayne@68: IDLEs, save it as a new custom theme or key set and it well be accessible jpayne@68: to older IDLEs.
jpayne@68:IDLE on macOS¶
jpayne@68:Under System Preferences: Dock, one can set “Prefer tabs when opening jpayne@68: documents” to “Always”. This setting is not compatible with the tk/tkinter jpayne@68: GUI framework used by IDLE, and it breaks a few IDLE features.
jpayne@68:Extensions¶
jpayne@68:IDLE contains an extension facility. Preferences for extensions can be jpayne@68: changed with the Extensions tab of the preferences dialog. See the jpayne@68: beginning of config-extensions.def in the idlelib directory for further jpayne@68: information. The only current default extension is zzdummy, an example jpayne@68: also used for testing.
jpayne@68: