Skip to content

Commit 188aedf

Browse files
authored
bpo-25514: Improve IDLE's connection refused message (#2177)
When IDLE fail to start because the socket connection fails, direct people to a new subsection of the IDLE doc listing various causes and remedies.
1 parent 8f6eeaf commit 188aedf

File tree

4 files changed

+119
-35
lines changed

4 files changed

+119
-35
lines changed

Doc/library/idle.rst

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -552,6 +552,50 @@ If there are arguments:
552552
``sys.argv`` reflects the arguments passed to IDLE itself.
553553

554554

555+
Startup failure
556+
^^^^^^^^^^^^^^^
557+
558+
IDLE uses a socket to communicate between the IDLE GUI process and the user
559+
code execution process. A connection must be established whenever the Shell
560+
starts or restarts. (The latter is indicated by a divider line that says
561+
'RESTART'). If the user process fails to connect to the GUI process, it
562+
displays a ``Tk`` error box with a 'cannot connect' message that directs the
563+
user here. It then exits.
564+
565+
A common cause of failure is a user-written file with the same name as a
566+
standard library module, such as *random.py* and *tkinter.py*. When such a
567+
file is located in the same directory as a file that is about to be run,
568+
IDLE cannot import the stdlib file. The current fix is to rename the
569+
user file.
570+
571+
Though less common than in the past, an antivirus or firewall program may
572+
stop the connection. If the program cannot be taught to allow the
573+
connection, then it must be turned off for IDLE to work. It is safe to
574+
allow this internal connection because no data is visible on external
575+
ports. A similar problem is a network mis-configuration that blocks
576+
connections.
577+
578+
Python installation issues occasionally stop IDLE: multiple versions can
579+
clash, or a single installation might need admin access. If one undo the
580+
clash, or cannot or does not want to run as admin, it might be easiest to
581+
completely remove Python and start over.
582+
583+
A zombie pythonw.exe process could be a problem. On Windows, use Task
584+
Manager to detect and stop one. Sometimes a restart initiated by a program
585+
crash or Keyboard Interrupt (control-C) may fail to connect. Dismissing
586+
the error box or Restart Shell on the Shell menu may fix a temporary problem.
587+
588+
When IDLE first starts, it attempts to read user configuration files in
589+
~/.idlerc/ (~ is one's home directory). If there is a problem, an error
590+
message should be displayed. Leaving aside random disk glitches, this can
591+
be prevented by never editing the files by hand, using the configuration
592+
dialog, under Options, instead Options. Once it happens, the solution may
593+
be to delete one or more of the configuration files.
594+
595+
If IDLE quits with no message, and it was not started from a console, try
596+
starting from a console (``python -m idlelib)`` and see if a message appears.
597+
598+
555599
IDLE-console differences
556600
^^^^^^^^^^^^^^^^^^^^^^^^
557601

Lib/idlelib/help.html

Lines changed: 67 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,15 @@
66
<head>
77
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
88

9-
<title>25.5. IDLE &mdash; Python 3.5.2 documentation</title>
9+
<title>25.5. IDLE &mdash; Python 3.7.0a0 documentation</title>
1010

1111
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
1212
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
1313

1414
<script type="text/javascript">
1515
var DOCUMENTATION_OPTIONS = {
1616
URL_ROOT: '../',
17-
VERSION: '3.5.2',
17+
VERSION: '3.7.0a0',
1818
COLLAPSE_INDEX: false,
1919
FILE_SUFFIX: '.html',
2020
HAS_SOURCE: true
@@ -25,20 +25,23 @@
2525
<script type="text/javascript" src="../_static/doctools.js"></script>
2626
<script type="text/javascript" src="../_static/sidebar.js"></script>
2727
<link rel="search" type="application/opensearchdescription+xml"
28-
title="Search within Python 3.5.2 documentation"
28+
title="Search within Python 3.7.0a0 documentation"
2929
href="../_static/opensearch.xml"/>
3030
<link rel="author" title="About these documents" href="../about.html" />
3131
<link rel="copyright" title="Copyright" href="../copyright.html" />
32-
<link rel="top" title="Python 3.5.2 documentation" href="../contents.html" />
32+
<link rel="top" title="Python 3.7.0a0 documentation" href="../contents.html" />
3333
<link rel="up" title="25. Graphical User Interfaces with Tk" href="tk.html" />
3434
<link rel="next" title="25.6. Other Graphical User Interface Packages" href="othergui.html" />
3535
<link rel="prev" title="25.4. tkinter.scrolledtext — Scrolled Text Widget" href="tkinter.scrolledtext.html" />
3636
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
37+
<link rel="canonical" href="https://docs.python.org/3/library/idle.html" />
38+
3739
<script type="text/javascript" src="../_static/copybutton.js"></script>
3840

3941

4042

4143

44+
4245
</head>
4346
<body role="document">
4447
<div class="related" role="navigation" aria-label="related navigation">
@@ -60,7 +63,7 @@ <h3>Navigation</h3>
6063
style="vertical-align: middle; margin-top: -1px"/></li>
6164
<li><a href="https://www.python.org/">Python</a> &raquo;</li>
6265
<li>
63-
<a href="../index.html">3.5.2 Documentation</a> &raquo;
66+
<a href="../index.html">3.7.0a0 Documentation</a> &raquo;
6467
</li>
6568

6669
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &raquo;</li>
@@ -90,7 +93,7 @@ <h3>Navigation</h3>
9093

9194
<div class="section" id="idle">
9295
<span id="id1"></span><h1>25.5. IDLE<a class="headerlink" href="#idle" title="Permalink to this headline"></a></h1>
93-
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.5/Lib/idlelib">Lib/idlelib/</a></p>
96+
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/master/Lib/idlelib/">Lib/idlelib/</a></p>
9497
<hr class="docutils" id="index-0" />
9598
<p>IDLE is Python&#8217;s Integrated Development and Learning Environment.</p>
9699
<p>IDLE has the following features:</p>
@@ -271,7 +274,7 @@ <h3>25.5.1.6. Debug menu (Shell window only)<a class="headerlink" href="#debug-m
271274
</dl>
272275
<dl class="docutils" id="index-3">
273276
<dt>Debugger (toggle)</dt>
274-
<dd>When actived, code entered in the Shell or run from an Editor will run
277+
<dd>When activated, code entered in the Shell or run from an Editor will run
275278
under the debugger. In the Editor, breakpoints can be set with the context
276279
menu. This feature is still incomplete and somewhat experimental.</dd>
277280
<dt>Stack Viewer</dt>
@@ -380,7 +383,7 @@ <h2>25.5.2. Editing and navigation<a class="headerlink" href="#editing-and-navig
380383
<li><code class="kbd docutils literal"><span class="pre">C-e</span></code> end of line</li>
381384
<li><code class="kbd docutils literal"><span class="pre">C-k</span></code> kill line (but doesn&#8217;t put it in clipboard)</li>
382385
<li><code class="kbd docutils literal"><span class="pre">C-l</span></code> center window around the insertion point</li>
383-
<li><code class="kbd docutils literal"><span class="pre">C-b</span></code> go backwards one character without deleting (usually you can
386+
<li><code class="kbd docutils literal"><span class="pre">C-b</span></code> go backward one character without deleting (usually you can
384387
also use the cursor key for this)</li>
385388
<li><code class="kbd docutils literal"><span class="pre">C-f</span></code> go forward one character without deleting (usually you can
386389
also use the cursor key for this)</li>
@@ -399,7 +402,7 @@ <h3>25.5.2.1. Automatic indentation<a class="headerlink" href="#automatic-indent
399402
Python Shell window by one tab). After certain keywords (break, return etc.)
400403
the next line is dedented. In leading indentation, <code class="kbd docutils literal"><span class="pre">Backspace</span></code> deletes up
401404
to 4 spaces if they are there. <code class="kbd docutils literal"><span class="pre">Tab</span></code> inserts spaces (in the Python
402-
Shell window one tab), number depends on Indent width. Currently tabs
405+
Shell window one tab), number depends on Indent width. Currently, tabs
403406
are restricted to four spaces due to Tcl/Tk limitations.</p>
404407
<p>See also the indent/dedent region commands in the edit menu.</p>
405408
</div>
@@ -418,7 +421,7 @@ <h3>25.5.2.2. Completions<a class="headerlink" href="#completions" title="Permal
418421
<code class="kbd docutils literal"><span class="pre">C-space</span></code> will open a completions window. In an empty
419422
string, this will contain the files in the current directory. On a
420423
blank line, it will contain the built-in and user-defined functions and
421-
classes in the current name spaces, plus any modules imported. If some
424+
classes in the current namespaces, plus any modules imported. If some
422425
characters have been entered, the ACW will attempt to be more specific.</p>
423426
<p>If a string of characters is typed, the ACW selection will jump to the
424427
entry most closely matching those characters. Entering a <code class="kbd docutils literal"><span class="pre">tab</span></code> will
@@ -440,7 +443,7 @@ <h3>25.5.2.2. Completions<a class="headerlink" href="#completions" title="Permal
440443
</div>
441444
<div class="section" id="calltips">
442445
<h3>25.5.2.3. Calltips<a class="headerlink" href="#calltips" title="Permalink to this headline"></a></h3>
443-
<p>A calltip is shown when one types <code class="kbd docutils literal"><span class="pre">(</span></code> after the name of an <em>acccessible</em>
446+
<p>A calltip is shown when one types <code class="kbd docutils literal"><span class="pre">(</span></code> after the name of an <em>accessible</em>
444447
function. A name expression may include dots and subscripts. A calltip
445448
remains until it is clicked, the cursor is moved out of the argument area,
446449
or <code class="kbd docutils literal"><span class="pre">)</span></code> is typed. When the cursor is in the argument part of a definition,
@@ -532,11 +535,47 @@ <h3>25.5.3.1. Command line usage<a class="headerlink" href="#command-line-usage"
532535
<code class="docutils literal"><span class="pre">sys.argv</span></code> reflects the arguments passed to IDLE itself.</li>
533536
</ul>
534537
</div>
538+
<div class="section" id="startup-failure">
539+
<h3>25.5.3.2. Startup failure<a class="headerlink" href="#startup-failure" title="Permalink to this headline"></a></h3>
540+
<p>IDLE uses a socket to communicate between the IDLE GUI process and the user
541+
code execution process. A connection must be established whenever the Shell
542+
starts or restarts. (The latter is indicated by a divider line that says
543+
&#8216;RESTART&#8217;). If the user process fails to connect to the GUI process, it
544+
displays a <code class="docutils literal"><span class="pre">Tk</span></code> error box with a &#8216;cannot connect&#8217; message that directs the
545+
user here. It then exits.</p>
546+
<p>A common cause of failure is a user-written file with the same name as a
547+
standard library module, such as <em>random.py</em> and <em>tkinter.py</em>. When such a
548+
file is located in the same directory as a file that is about to be run,
549+
IDLE cannot import the stdlib file. The current fix is to rename the
550+
user file.</p>
551+
<p>Though less common than in the past, an antivirus or firewall program may
552+
stop the connection. If the program cannot be taught to allow the
553+
connection, then it must be turned off for IDLE to work. It is safe to
554+
allow this internal connection because no data is visible on external
555+
ports. A similar problem is a network mis-configuration that blocks
556+
connections.</p>
557+
<p>Python installation issues occasionally stop IDLE: multiple versions can
558+
clash, or a single installation might need admin access. If one undo the
559+
clash, or cannot or does not want to run as admin, it might be easiest to
560+
completely remove Python and start over.</p>
561+
<p>A zombie pythonw.exe process could be a problem. On Windows, use Task
562+
Manager to detect and stop one. Sometimes a restart initiated by a program
563+
crash or Keyboard Interrupt (control-C) may fail to connect. Dismissing
564+
the error box or Restart Shell on the Shell menu may fix a temporary problem.</p>
565+
<p>When IDLE first starts, it attempts to read user configuration files in
566+
~/.idlerc/ (~ is one&#8217;s home directory). If there is a problem, an error
567+
message should be displayed. Leaving aside random disk glitches, this can
568+
be prevented by never editing the files by hand, using the configuration
569+
dialog, under Options, instead Options. Once it happens, the solution may
570+
be to delete one or more of the configuration files.</p>
571+
<p>If IDLE quits with no message, and it was not started from a console, try
572+
starting from a console (<code class="docutils literal"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">idlelib)</span></code> and see if a message appears.</p>
573+
</div>
535574
<div class="section" id="idle-console-differences">
536-
<h3>25.5.3.2. IDLE-console differences<a class="headerlink" href="#idle-console-differences" title="Permalink to this headline"></a></h3>
575+
<h3>25.5.3.3. IDLE-console differences<a class="headerlink" href="#idle-console-differences" title="Permalink to this headline"></a></h3>
537576
<p>As much as possible, the result of executing Python code with IDLE is the
538577
same as executing the same code in a console window. However, the different
539-
interface and operation occasionally affects visible results. For instance,
578+
interface and operation occasionally affect visible results. For instance,
540579
<code class="docutils literal"><span class="pre">sys.modules</span></code> starts with more entries.</p>
541580
<p>IDLE also replaces <code class="docutils literal"><span class="pre">sys.stdin</span></code>, <code class="docutils literal"><span class="pre">sys.stdout</span></code>, and <code class="docutils literal"><span class="pre">sys.stderr</span></code> with
542581
objects that get input from and send output to the Shell window.
@@ -551,14 +590,14 @@ <h3>25.5.3.2. IDLE-console differences<a class="headerlink" href="#idle-console-
551590
defined for each statement.</p>
552591
</div>
553592
<div class="section" id="running-without-a-subprocess">
554-
<h3>25.5.3.3. Running without a subprocess<a class="headerlink" href="#running-without-a-subprocess" title="Permalink to this headline"></a></h3>
593+
<h3>25.5.3.4. Running without a subprocess<a class="headerlink" href="#running-without-a-subprocess" title="Permalink to this headline"></a></h3>
555594
<p>By default, IDLE executes user code in a separate subprocess via a socket,
556595
which uses the internal loopback interface. This connection is not
557596
externally visible and no data is sent to or received from the Internet.
558597
If firewall software complains anyway, you can ignore it.</p>
559598
<p>If the attempt to make the socket connection fails, Idle will notify you.
560599
Such failures are sometimes transient, but if persistent, the problem
561-
may be either a firewall blocking the connecton or misconfiguration of
600+
may be either a firewall blocking the connection or misconfiguration of
562601
a particular system. Until the problem is fixed, one can run Idle with
563602
the -n command line switch.</p>
564603
<p>If IDLE is started with the -n command line switch it will run in a
@@ -590,12 +629,12 @@ <h3>25.5.4.1. Additional help sources<a class="headerlink" href="#additional-hel
590629
<h3>25.5.4.2. Setting preferences<a class="headerlink" href="#setting-preferences" title="Permalink to this headline"></a></h3>
591630
<p>The font preferences, highlighting, keys, and general preferences can be
592631
changed via Configure IDLE on the Option menu. Keys can be user defined;
593-
IDLE ships with four built in key sets. In addition a user can create a
632+
IDLE ships with four built-in key sets. In addition, a user can create a
594633
custom key set in the Configure IDLE dialog under the keys tab.</p>
595634
</div>
596635
<div class="section" id="extensions">
597636
<h3>25.5.4.3. Extensions<a class="headerlink" href="#extensions" title="Permalink to this headline"></a></h3>
598-
<p>IDLE contains an extension facility. Peferences for extensions can be
637+
<p>IDLE contains an extension facility. Preferences for extensions can be
599638
changed with Configure Extensions. See the beginning of config-extensions.def
600639
in the idlelib directory for further information. The default extensions
601640
are currently:</p>
@@ -646,8 +685,9 @@ <h3><a href="../contents.html">Table Of Contents</a></h3>
646685
</li>
647686
<li><a class="reference internal" href="#startup-and-code-execution">25.5.3. Startup and code execution</a><ul>
648687
<li><a class="reference internal" href="#command-line-usage">25.5.3.1. Command line usage</a></li>
649-
<li><a class="reference internal" href="#idle-console-differences">25.5.3.2. IDLE-console differences</a></li>
650-
<li><a class="reference internal" href="#running-without-a-subprocess">25.5.3.3. Running without a subprocess</a></li>
688+
<li><a class="reference internal" href="#startup-failure">25.5.3.2. Startup failure</a></li>
689+
<li><a class="reference internal" href="#idle-console-differences">25.5.3.3. IDLE-console differences</a></li>
690+
<li><a class="reference internal" href="#running-without-a-subprocess">25.5.3.4. Running without a subprocess</a></li>
651691
</ul>
652692
</li>
653693
<li><a class="reference internal" href="#help-and-preferences">25.5.4. Help and preferences</a><ul>
@@ -670,8 +710,11 @@ <h4>Next topic</h4>
670710
<h3>This Page</h3>
671711
<ul class="this-page-menu">
672712
<li><a href="../bugs.html">Report a Bug</a></li>
673-
<li><a href="../_sources/library/idle.txt"
674-
rel="nofollow">Show Source</a></li>
713+
<li>
714+
<a href="https://github.com/python/cpython/blob/master/Doc/library/idle.rst"
715+
rel="nofollow">Show Source
716+
</a>
717+
</li>
675718
</ul>
676719
</div>
677720
</div>
@@ -697,7 +740,7 @@ <h3>Navigation</h3>
697740
style="vertical-align: middle; margin-top: -1px"/></li>
698741
<li><a href="https://www.python.org/">Python</a> &raquo;</li>
699742
<li>
700-
<a href="../index.html">3.5.2 Documentation</a> &raquo;
743+
<a href="../index.html">3.7.0a0 Documentation</a> &raquo;
701744
</li>
702745

703746
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &raquo;</li>
@@ -720,12 +763,12 @@ <h3>Navigation</h3>
720763
</ul>
721764
</div>
722765
<div class="footer">
723-
&copy; <a href="../copyright.html">Copyright</a> 2001-2016, Python Software Foundation.
766+
&copy; <a href="../copyright.html">Copyright</a> 2001-2017, Python Software Foundation.
724767
<br />
725768
The Python Software Foundation is a non-profit corporation.
726769
<a href="https://www.python.org/psf/donations/">Please donate.</a>
727770
<br />
728-
Last updated on Sep 12, 2016.
771+
Last updated on Jun 13, 2017.
729772
<a href="../bugs.html">Found a bug</a>?
730773
<br />
731774
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.6.

Lib/idlelib/help.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -260,7 +260,7 @@ def copy_strip():
260260
open(dst, 'wb') as out:
261261
for line in inn:
262262
out.write(line.rstrip() + b'\n')
263-
print('idle.html copied to help.html')
263+
print(f'{src} copied to {dst}')
264264

265265
def show_idlehelp(parent):
266266
"Create HelpWindow; called from Idle Help event handler."

Lib/idlelib/run.py

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -180,19 +180,16 @@ def manage_socket(address):
180180
server.handle_request() # A single request only
181181

182182
def show_socket_error(err, address):
183+
"Display socket error from manage_socket."
183184
import tkinter
184-
import tkinter.messagebox as tkMessageBox
185+
from tkinter.messagebox import showerror
185186
root = tkinter.Tk()
186187
root.withdraw()
187-
if err.args[0] == 61: # connection refused
188-
msg = "IDLE's subprocess can't connect to %s:%d. This may be due "\
189-
"to your personal firewall configuration. It is safe to "\
190-
"allow this internal connection because no data is visible on "\
191-
"external ports." % address
192-
tkMessageBox.showerror("IDLE Subprocess Error", msg, parent=root)
193-
else:
194-
tkMessageBox.showerror("IDLE Subprocess Error",
195-
"Socket Error: %s" % err.args[1], parent=root)
188+
msg = f"IDLE's subprocess can't connect to {address[0]}:{address[1]}.\n"\
189+
f"Fatal OSError #{err.errno}: {err.strerror}.\n"\
190+
f"See the 'Startup failure' section of the IDLE doc, online at\n"\
191+
f"https://docs.python.org/3/library/idle.html#startup-failure"
192+
showerror("IDLE Subprocess Error", msg, parent=root)
196193
root.destroy()
197194

198195
def print_exception():

0 commit comments

Comments
 (0)