python · richardsheridan · Jul 3, 2020 · Jul 3, 2020 · Jul 3, 2020 · Jul 3, 2020
diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
@@ -70,10 +70,7 @@ Tkinter Modules
 
 Most of the time, :mod:`tkinter` is all you really need, but a number of
 additional modules are available as well.  The Tk interface is located in a
-binary module named :mod:`_tkinter`. This module contains the low-level
-interface to Tk, and should never be used directly by application programmers.
-It is usually a shared library (or DLL), but might in some cases be statically
-linked with the Python interpreter.
+binary module named :mod:`_tkinter`.
 
 In addition to the Tk interface module, :mod:`tkinter` includes a number of
 Python modules, :mod:`tkinter.constants` being one of the most important.
@@ -82,10 +79,6 @@ so, usually, to use Tkinter all you need is a simple import statement::
 
    import tkinter
 
-Or, more often::
-
-   from tkinter import *
-
 
 .. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1)
 
@@ -95,6 +88,38 @@ Or, more often::
 
    .. FIXME: The following keyword arguments are currently recognized:
 
+   Below are a few of the methods provided by the :class:`Tk` class.
+
+   .. sectionauthor:: Richard Sheridan
+
+   .. method:: mainloop(threshold)
+
+      Enters the main loop of Tkinter. This repeatedly dispatches Tcl events
+      until either :meth:`Tk.quit` is called, the number of open windows drops
+      below ``threshold``, or an error occurs while executing events. Usually
+      the default threshold of 0 is appropriate.
+
+   .. method:: quit()
+
+      Signals the Tkinter main loop to stop dispatching.
+      The main loop will exit AFTER the current Tcl event handler is
+      finished calling. If quit is called outside the context of a Tcl
+      event, for example from a thread, the main loop will not exit
+      until after the NEXT event is dispatched. If no more events are
+      forthcoming, main loop will keep blocking even if quit has been
+      called. In that case, call ``after(0, quit)`` instead.
+
+   .. method:: dispatching()
+
+      Determines if the Tkinter main loop is running. Returns True if the main
+      loop is running, or returns False if the main loop is not running. It is
+      possible for some entity other than the main loop to be dispatching
+      events. Some examples are: calling the :meth:`Tk.update` command,
+      :meth:`_tkinter.tkapp.doonevent`, and the python command line EventHook.
+      :meth:`Tk.dispatching` does not provide any information about entities
+      dispatching other than :meth:`Tk.mainloop`.
+
+      .. versionadded:: 3.10
 
 .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0)
 
@@ -106,7 +131,6 @@ Or, more often::
    created by the :func:`Tcl` object can have a Toplevel window created (and the Tk
    subsystem initialized) by calling its :meth:`loadtk` method.
 
-
 Other modules that provide Tk support include:
 
 :mod:`tkinter.colorchooser`

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
@@ -117,6 +117,22 @@ Add :data:`sys.orig_argv` attribute: the list of the original command line
 arguments passed to the Python executable.
 (Contributed by Victor Stinner in :issue:`23427`.)
 
+tkinter
+-------
+
+XXX Added :meth:`tkinter.dispatching`, :meth:`tkinter.Misc.dispatching`, and
+:meth:`_tkinter.tkapp.dispatching`.
+You can reliably call these to determine if the tkinter mainloop is running.
+
+Some internal thread waiting behavior has been deprecated to preserve the
+correctness of the new dispatching methods.
+
+Added another new method :meth:`_tkinter.tkapp.setmainloopwaitattempts` which
+can be used to obtain future thread waiting behavior.
+
+(see also Deprecated section)
+(Contributed by Richard Sheridan in :issue:`41176`.)
+
 
 Optimizations
 =============
@@ -130,6 +146,13 @@ Optimizations
 Deprecated
 ==========
 
+XXX The :mod:`tkinter` module has deprected the undocumented behavior where a
+thread will implicitly wait up to one second for the main thread to enter
+the main loop and then fail.
+The undocumented :meth:`_tkinter.tkapp.willdispatch` method which sidesteps
+this behavior has also been deprecated.
+(See also tkinter in the Improved Modules section)
+(Contributed by Richard Sheridan in :issue:`41176`.)
 
 Removed
 =======

diff --git a/Lib/tkinter/__init__.py b/Lib/tkinter/__init__.py
@@ -590,9 +590,20 @@ def get(self):
             raise ValueError("invalid literal for getboolean()")
 
 
-def mainloop(n=0):
-    """Run the main loop of Tcl."""
-    _default_root.tk.mainloop(n)
+def mainloop(threshold=0):
+    """Call the main loop of Tkinter."""
+    _default_root.tk.mainloop(threshold)
+
+
+def dispatching():
+    """Determine if the Tkinter main loop is running.
+
+    Returns True if the main loop is running.
+    Returns False if the main loop is not running.
+
+    NOTE: Using update will dispatch events without the main
+          loop. Dispatching will return False in these cases."""
+    return _default_root.tk.dispatching()
 
 
 getint = int
@@ -1303,13 +1314,13 @@ def winfo_y(self):
             self.tk.call('winfo', 'y', self._w))
 
     def update(self):
-        """Enter event loop until all pending events have been processed by Tcl."""
+        """Process all events, including idle tasks, in the Tcl queue."""
         self.tk.call('update')
 
     def update_idletasks(self):
-        """Enter event loop until all idle callbacks have been called. This
-        will update the display of windows but not process events caused by
-        the user."""
+        """Process all idle callbacks in the Tcl queue.
+        This will update the display of windows but not process events
+        caused by the user."""
         self.tk.call('update', 'idletasks')
 
     def bindtags(self, tagList=None):
@@ -1417,12 +1428,30 @@ def unbind_class(self, className, sequence):
         all functions."""
         self.tk.call('bind', className , sequence, '')
 
-    def mainloop(self, n=0):
-        """Call the mainloop of Tk."""
-        self.tk.mainloop(n)
+    def mainloop(self, threshold=0):
+        """Call the main loop of Tkinter."""
+        self.tk.mainloop(threshold)
+
+    def dispatching(self):
+        """Determine if the Tkinter main loop is running.
+
+        Returns True if the main loop is running.
+        Returns False if the main loop is not running.
+
+        NOTE: Using update will dispatch events without the main
+              loop. Dispatching will return False in these cases."""
+        return self.tk.dispatching()
 
     def quit(self):
-        """Quit the Tcl interpreter. All widgets will be destroyed."""
+        """Signal the Tkinter main loop to stop dispatching.
+
+        The main loop will exit AFTER the current Tcl event handler is
+        finished calling. If quit is called outside the context of a Tcl
+        event, for example from a thread, the main loop will not exit
+        until after the NEXT event is dispatched. If no more events are
+        forthcoming, main loop will keep blocking even if quit has been
+        called. In that case, have the thread call after(0, quit) instead.
+        """
         self.tk.quit()
 
     def _getints(self, string):

diff --git a/Lib/tkinter/test/support.py b/Lib/tkinter/test/support.py
@@ -22,7 +22,7 @@ def setUpClass(cls):
 
     @classmethod
     def tearDownClass(cls):
-        cls.root.update_idletasks()
+        cls.root.update()
         cls.root.destroy()
         del cls.root
         tkinter._default_root = None
@@ -38,7 +38,7 @@ def tearDown(self):
 
 def destroy_default_root():
     if getattr(tkinter, '_default_root', None):
-        tkinter._default_root.update_idletasks()
+        tkinter._default_root.update()
         tkinter._default_root.destroy()
         tkinter._default_root = None
 

diff --git a/Lib/tkinter/test/test_tkinter/test_misc.py b/Lib/tkinter/test/test_tkinter/test_misc.py
@@ -1,5 +1,7 @@
 import unittest
 import tkinter
+import threading
+import time
 from test import support
 from tkinter.test.support import AbstractTkTest
 
@@ -109,15 +111,15 @@ def callback(start=0, step=1):
         idle1 = root.after_idle(callback)
         self.assertIn(idle1, root.tk.call('after', 'info'))
         (script, _) = root.tk.splitlist(root.tk.call('after', 'info', idle1))
-        root.update_idletasks()  # Process all pending events.
+        root.update()  # Process all pending events.
         self.assertEqual(count, 1)
         with self.assertRaises(tkinter.TclError):
             root.tk.call(script)
 
         # Set up with callback with args.
         count = 0
         idle1 = root.after_idle(callback, 42, 11)
-        root.update_idletasks()  # Process all pending events.
+        root.update()  # Process all pending events.
         self.assertEqual(count, 53)
 
         # Cancel before called.
@@ -192,6 +194,100 @@ def test_clipboard_astral(self):
         with self.assertRaises(tkinter.TclError):
             root.clipboard_get()
 
+    def test_mainloop_dispatching(self):
+        # reconstruct default root destroyed by AbstractTkTest
+        root = tkinter._default_root = self.root
+        for obj in (root.tk, root, tkinter):
+            self.assertFalse(obj.dispatching())
+            root.after(0, lambda:self.assertTrue(obj.dispatching()))
+
+            # guarantees mainloop end after first call to Tcl_DoOneEvent
+            root.after(0, root.quit)
+
+            root.mainloop()
+            self.assertFalse(obj.dispatching())
+
+    def test_willdispatch(self):
+        root = self.root
+        self.assertFalse(root.dispatching())
+        with self.assertWarns(DeprecationWarning):
+            root.tk.willdispatch()
+        self.assertTrue(root.dispatching())
+        # reset dispatching flag
+        root.after(0,root.quit)
+        root.mainloop()
+        self.assertFalse(root.dispatching())
+
+    def test_thread_must_wait_for_mainloop(self):
+        # remove test on eventual WaitForMainloop removal
+        sentinel = object()
+        thread_properly_raises = sentinel
+        thread_dispatching_early = sentinel
+        thread_dispatching_eventually = sentinel
+
+        def target():
+            nonlocal thread_dispatching_early
+            nonlocal thread_properly_raises
+            nonlocal thread_dispatching_eventually
+
+            try:
+                thread_dispatching_early = root.dispatching()
+                root.after(0)  # Null op
+            except RuntimeError as e:
+                if str(e) == "main thread is not in main loop":
+                    thread_properly_raises=True
+                else:
+                    thread_properly_raises=False
+                    raise
+            else:
+                thread_properly_raises=False
+                return
+            finally:
+                # must guarantee that any reason not to run mainloop
+                # is flagged in the above try/except/else and will
+                # keep the main thread from calling root.mainloop()
+                ready_for_mainloop.set()
+
+            # self.assertTrue(root.dispatching()) but patient
+            for i in range(1000):
+                if root.dispatching():
+                    thread_dispatching_eventually = True
+                    break
+                time.sleep(0.01)
+            else:  # if not break
+                thread_dispatching_eventually = False
+            root.after(0, root.quit)
+
+        root = self.root
+
+        with self.assertWarns(DeprecationWarning):
+            root.tk.setmainloopwaitattempts(0)
+
+        try:
+            ready_for_mainloop = threading.Event()
+            thread = threading.Thread(target=target)
+            self.assertFalse(root.dispatching())
+            thread.start()
+            ready_for_mainloop.wait()
+
+            # if these fail we don't want to risk starting mainloop
+            self.assertFalse(thread_dispatching_early is sentinel)
+            self.assertFalse(thread_dispatching_early)
+            self.assertFalse(thread_properly_raises is sentinel)
+            self.assertTrue(thread_properly_raises)
+
+            root.mainloop()
+            self.assertFalse(root.dispatching())
+            thread.join()
+        finally:
+            # this global *must* be reset
+            with self.assertWarns(DeprecationWarning):
+                root.tk.setmainloopwaitattempts(10)
+
+        self.assertFalse(thread_dispatching_eventually is sentinel)
+        self.assertTrue(thread_dispatching_eventually)
+
+
 
 tests_gui = (MiscTest, )
 

diff --git a/Lib/tkinter/test/test_ttk/test_extensions.py b/Lib/tkinter/test/test_ttk/test_extensions.py
@@ -10,7 +10,7 @@
 class LabeledScaleTest(AbstractTkTest, unittest.TestCase):
 
     def tearDown(self):
-        self.root.update_idletasks()
+        self.root.update()
         super().tearDown()
 
     def test_widget_destroy(self):
@@ -219,7 +219,7 @@ def test_widget_destroy(self):
         var = tkinter.StringVar(self.root)
         optmenu = ttk.OptionMenu(self.root, var)
         name = var._name
-        optmenu.update_idletasks()
+        optmenu.update()
         optmenu.destroy()
         self.assertEqual(optmenu.tk.globalgetvar(name), var.get())
         del var