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.

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
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

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."

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():