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