bpo-25514: Improve IDLE's connection refused message (#2177)

terryjreedy · web-flow · commit 188aedf8bb62 · 2017-06-13T21:32:16.000-04:00
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.
diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
@@ -552,6 +552,50 @@ If there are arguments:
   ``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.
+
+
 IDLE-console differences
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/Lib/idlelib/help.html b/Lib/idlelib/help.html
@@ -6,15 +6,15 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>25.5. IDLE &mdash; Python 3.5.2 documentation</title>
+    <title>25.5. IDLE &mdash; Python 3.7.0a0 documentation</title>
 
     <link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
 
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '../',
-        VERSION:     '3.5.2',
+        VERSION:     '3.7.0a0',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -25,20 +25,23 @@
     <script type="text/javascript" src="../_static/doctools.js"></script>
     <script type="text/javascript" src="../_static/sidebar.js"></script>
     <link rel="search" type="application/opensearchdescription+xml"
-          title="Search within Python 3.5.2 documentation"
+          title="Search within Python 3.7.0a0 documentation"
           href="../_static/opensearch.xml"/>
     <link rel="author" title="About these documents" href="../about.html" />
     <link rel="copyright" title="Copyright" href="../copyright.html" />
-    <link rel="top" title="Python 3.5.2 documentation" href="../contents.html" />
+    <link rel="top" title="Python 3.7.0a0 documentation" href="../contents.html" />
     <link rel="up" title="25. Graphical User Interfaces with Tk" href="tk.html" />
     <link rel="next" title="25.6. Other Graphical User Interface Packages" href="othergui.html" />
     <link rel="prev" title="25.4. tkinter.scrolledtext — Scrolled Text Widget" href="tkinter.scrolledtext.html" />
     <link rel="shortcut icon" type="image/png" href="../_static/py.png" />
+    <link rel="canonical" href="https://docs.python.org/3/library/idle.html" />
+
     <script type="text/javascript" src="../_static/copybutton.js"></script>
 
 
 
 
+
   </head>
   <body role="document">
     <div class="related" role="navigation" aria-label="related navigation">
@@ -60,7 +63,7 @@ <h3>Navigation</h3>
                  style="vertical-align: middle; margin-top: -1px"/></li>
         <li><a href="https://www.python.org/">Python</a> &raquo;</li>
         <li>
-          <a href="../index.html">3.5.2 Documentation</a> &raquo;
+          <a href="../index.html">3.7.0a0 Documentation</a> &raquo;
         </li>
 
           <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>
 
   <div class="section" id="idle">
 <span id="id1"></span><h1>25.5. IDLE<a class="headerlink" href="#idle" title="Permalink to this headline">¶</a></h1>
-<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.5/Lib/idlelib">Lib/idlelib/</a></p>
+<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/master/Lib/idlelib/">Lib/idlelib/</a></p>
 <hr class="docutils" id="index-0" />
 <p>IDLE is Python&#8217;s Integrated Development and Learning Environment.</p>
 <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
 </dl>
 <dl class="docutils" id="index-3">
 <dt>Debugger (toggle)</dt>
-<dd>When actived, code entered in the Shell or run from an Editor will run
+<dd>When activated, code entered in the Shell or run from an Editor will run
 under the debugger.  In the Editor, breakpoints can be set with the context
 menu.  This feature is still incomplete and somewhat experimental.</dd>
 <dt>Stack Viewer</dt>
@@ -380,7 +383,7 @@ <h2>25.5.2. Editing and navigation<a class="headerlink" href="#editing-and-navig
 <li><code class="kbd docutils literal"><span class="pre">C-e</span></code> end of line</li>
 <li><code class="kbd docutils literal"><span class="pre">C-k</span></code> kill line (but doesn&#8217;t put it in clipboard)</li>
 <li><code class="kbd docutils literal"><span class="pre">C-l</span></code> center window around the insertion point</li>
-<li><code class="kbd docutils literal"><span class="pre">C-b</span></code> go backwards one character without deleting (usually you can
+<li><code class="kbd docutils literal"><span class="pre">C-b</span></code> go backward one character without deleting (usually you can
 also use the cursor key for this)</li>
 <li><code class="kbd docutils literal"><span class="pre">C-f</span></code> go forward one character without deleting (usually you can
 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
 Python Shell window by one tab).  After certain keywords (break, return etc.)
 the next line is dedented.  In leading indentation, <code class="kbd docutils literal"><span class="pre">Backspace</span></code> deletes up
 to 4 spaces if they are there. <code class="kbd docutils literal"><span class="pre">Tab</span></code> inserts spaces (in the Python
-Shell window one tab), number depends on Indent width. Currently tabs
+Shell window one tab), number depends on Indent width. Currently, tabs
 are restricted to four spaces due to Tcl/Tk limitations.</p>
 <p>See also the indent/dedent region commands in the edit menu.</p>
 </div>
@@ -418,7 +421,7 @@ <h3>25.5.2.2. Completions<a class="headerlink" href="#completions" title="Permal
 <code class="kbd docutils literal"><span class="pre">C-space</span></code> 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 name spaces, plus any modules imported. If some
+classes in the current namespaces, plus any modules imported. If some
 characters have been entered, the ACW will attempt to be more specific.</p>
 <p>If a string of characters is typed, the ACW selection will jump to the
 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
 </div>
 <div class="section" id="calltips">
 <h3>25.5.2.3. Calltips<a class="headerlink" href="#calltips" title="Permalink to this headline">¶</a></h3>
-<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>
+<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>
 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 <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"
 <code class="docutils literal"><span class="pre">sys.argv</span></code> reflects the arguments passed to IDLE itself.</li>
 </ul>
 </div>
+<div class="section" id="startup-failure">
+<h3>25.5.3.2. Startup failure<a class="headerlink" href="#startup-failure" title="Permalink to this headline">¶</a></h3>
+<p>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
+&#8216;RESTART&#8217;). If the user process fails to connect to the GUI process, it
+displays a <code class="docutils literal"><span class="pre">Tk</span></code> error box with a &#8216;cannot connect&#8217; message that directs the
+user here.  It then exits.</p>
+<p>A common cause of failure is a user-written file with the same name as a
+standard library module, such as <em>random.py</em> and <em>tkinter.py</em>. 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.</p>
+<p>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.</p>
+<p>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.</p>
+<p>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.</p>
+<p>When IDLE first starts, it attempts to read user configuration files in
+~/.idlerc/ (~ is one&#8217;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.</p>
+<p>If IDLE quits with no message, and it was not started from a console, try
+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>
+</div>
 <div class="section" id="idle-console-differences">
-<h3>25.5.3.2. IDLE-console differences<a class="headerlink" href="#idle-console-differences" title="Permalink to this headline">¶</a></h3>
+<h3>25.5.3.3. IDLE-console differences<a class="headerlink" href="#idle-console-differences" title="Permalink to this headline">¶</a></h3>
 <p>As much as possible, the result of executing Python code with IDLE is the
 same as executing the same code in a console window.  However, the different
-interface and operation occasionally affects visible results.  For instance,
+interface and operation occasionally affect visible results.  For instance,
 <code class="docutils literal"><span class="pre">sys.modules</span></code> starts with more entries.</p>
 <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
 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-
 defined for each statement.</p>
 </div>
 <div class="section" id="running-without-a-subprocess">
-<h3>25.5.3.3. Running without a subprocess<a class="headerlink" href="#running-without-a-subprocess" title="Permalink to this headline">¶</a></h3>
+<h3>25.5.3.4. Running without a subprocess<a class="headerlink" href="#running-without-a-subprocess" title="Permalink to this headline">¶</a></h3>
 <p>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.</p>
 <p>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 connecton or misconfiguration of
+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.</p>
 <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
 <h3>25.5.4.2. Setting preferences<a class="headerlink" href="#setting-preferences" title="Permalink to this headline">¶</a></h3>
 <p>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
+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.</p>
 </div>
 <div class="section" id="extensions">
 <h3>25.5.4.3. Extensions<a class="headerlink" href="#extensions" title="Permalink to this headline">¶</a></h3>
-<p>IDLE contains an extension facility.  Peferences for extensions can be
+<p>IDLE contains an extension facility.  Preferences for extensions can be
 changed with Configure Extensions. See the beginning of config-extensions.def
 in the idlelib directory for further information.  The default extensions
 are currently:</p>
@@ -646,8 +685,9 @@ <h3><a href="../contents.html">Table Of Contents</a></h3>
 </li>
 <li><a class="reference internal" href="#startup-and-code-execution">25.5.3. Startup and code execution</a><ul>
 <li><a class="reference internal" href="#command-line-usage">25.5.3.1. Command line usage</a></li>
-<li><a class="reference internal" href="#idle-console-differences">25.5.3.2. IDLE-console differences</a></li>
-<li><a class="reference internal" href="#running-without-a-subprocess">25.5.3.3. Running without a subprocess</a></li>
+<li><a class="reference internal" href="#startup-failure">25.5.3.2. Startup failure</a></li>
+<li><a class="reference internal" href="#idle-console-differences">25.5.3.3. IDLE-console differences</a></li>
+<li><a class="reference internal" href="#running-without-a-subprocess">25.5.3.4. Running without a subprocess</a></li>
 </ul>
 </li>
 <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>
     <h3>This Page</h3>
     <ul class="this-page-menu">
       <li><a href="../bugs.html">Report a Bug</a></li>
-      <li><a href="../_sources/library/idle.txt"
-            rel="nofollow">Show Source</a></li>
+      <li>
+        <a href="https://github.com/python/cpython/blob/master/Doc/library/idle.rst"
+            rel="nofollow">Show Source
+        </a>
+      </li>
     </ul>
   </div>
         </div>
@@ -697,7 +740,7 @@ <h3>Navigation</h3>
                  style="vertical-align: middle; margin-top: -1px"/></li>
         <li><a href="https://www.python.org/">Python</a> &raquo;</li>
         <li>
-          <a href="../index.html">3.5.2 Documentation</a> &raquo;
+          <a href="../index.html">3.7.0a0 Documentation</a> &raquo;
         </li>
 
           <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>
       </ul>
     </div>
     <div class="footer">
-    &copy; <a href="../copyright.html">Copyright</a> 2001-2016, Python Software Foundation.
+    &copy; <a href="../copyright.html">Copyright</a> 2001-2017, Python Software Foundation.
     <br />
     The Python Software Foundation is a non-profit corporation.
     <a href="https://www.python.org/psf/donations/">Please donate.</a>
     <br />
-    Last updated on Sep 12, 2016.
+    Last updated on Jun 13, 2017.
     <a href="../bugs.html">Found a bug</a>?
     <br />
     Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.6.
diff --git a/Lib/idlelib/help.py b/Lib/idlelib/help.py
@@ -260,7 +260,7 @@ def copy_strip():
          open(dst, 'wb') as out:
         for line in inn:
             out.write(line.rstrip() + b'\n')
-    print('idle.html copied to help.html')
+    print(f'{src} copied to {dst}')
 
 def show_idlehelp(parent):
     "Create HelpWindow; called from Idle Help event handler."
diff --git a/Lib/idlelib/run.py b/Lib/idlelib/run.py
@@ -180,19 +180,16 @@ def manage_socket(address):
     server.handle_request() # A single request only
 
 def show_socket_error(err, address):
+    "Display socket error from manage_socket."
     import tkinter
-    import tkinter.messagebox as tkMessageBox
+    from tkinter.messagebox import showerror
     root = tkinter.Tk()
     root.withdraw()
-    if err.args[0] == 61: # connection refused
-        msg = "IDLE's subprocess can't connect to %s:%d.  This may be due "\
-              "to your personal firewall configuration.  It is safe to "\
-              "allow this internal connection because no data is visible on "\
-              "external ports." % address
-        tkMessageBox.showerror("IDLE Subprocess Error", msg, parent=root)
-    else:
-        tkMessageBox.showerror("IDLE Subprocess Error",
-                               "Socket Error: %s" % err.args[1], parent=root)
+    msg = f"IDLE's subprocess can't connect to {address[0]}:{address[1]}.\n"\
+          f"Fatal OSError #{err.errno}: {err.strerror}.\n"\
+          f"See the 'Startup failure' section of the IDLE doc, online at\n"\
+          f"https://docs.python.org/3/library/idle.html#startup-failure"
+    showerror("IDLE Subprocess Error", msg, parent=root)
     root.destroy()
 
 def print_exception():
