Make blocking consistent (#14098)

Author: cbrnr

doc/changes/dev/14098.apichange.rst

@@ -0,0 +1 @@
+The ``block`` parameter of :meth:`mne.time_frequency.Spectrum.plot_topo`, the legacy ``plot_psd_topo`` methods, and ``mne.viz.plot_raw_psd_topo`` is deprecated and will be removed in MNE 1.15; these plots now follow Matplotlib's blocking behavior, by `Clemens Brunner`_.

doc/changes/dev/14098.bugfix.rst

@@ -0,0 +1 @@
+Fixed :func:`~mne.viz.plot_evoked_topomap` and :func:`~mne.viz.plot_sensors` (and the ``plot_sensors`` methods) to follow Matplotlib's blocking behavior when ``show=True`` instead of returning immediately; ``plot_sensors`` keeps its ``block`` argument (default now ``None``), by `Clemens Brunner`_.

mne/_fiff/meas_info.py

@@ -690,7 +690,7 @@ def plot_sensors(
         ch_groups=None,
         to_sphere=True,
         axes=None,
-        block=False,
+        block=None,
         show=True,
         sphere=None,
         *,
@@ -736,11 +736,18 @@ def plot_sensors(
             instance of Axes3D. If None (default), a new axes will be created.
 
             .. versionadded:: 0.13.0
-        block : bool
-            Whether to halt program execution until the figure is closed.
-            Defaults to False.
+        block : bool | None
+            Whether to halt program execution until the figure is closed. By default
+            (``None``) this follows :func:`matplotlib.pyplot.show`: it blocks unless
+            Matplotlib's interactive mode is on (see :func:`matplotlib.pyplot.ion`), in
+            which case it returns immediately. Set to ``True`` to force blocking, which
+            is useful with ``kind="select"`` to collect the interactive selection
+            synchronously when interactive mode is on.
 
             .. versionadded:: 0.13.0
+            .. versionchanged:: 1.13
+               The default changed from ``False`` to ``None`` (follow
+               Matplotlib).
         show : bool
             Show figure if True. Defaults to True.
         %(sphere_topomap_auto)s

mne/time_frequency/spectrum.py

@@ -161,7 +161,7 @@ def plot_psd_topo(
         fig_facecolor="k",
         axis_facecolor="k",
         axes=None,
-        block=False,
+        block=None,
         show=True,
         n_jobs=None,
         verbose=None,
@@ -181,7 +181,9 @@ def plot_psd_topo(
         %(fig_facecolor)s
         %(axis_facecolor)s
         %(axes_spectrum_plot_topo)s
-        %(block)s
+        block : bool
+            This parameter is deprecated and will be removed in MNE 1.15; blocking now
+            follows Matplotlib's behavior (see ``show``).
         %(show)s
         %(n_jobs)s
         %(verbose)s
@@ -726,7 +728,7 @@ def plot_topo(
         fig_facecolor="k",
         axis_facecolor="k",
         axes=None,
-        block=False,
+        block=None,
         show=True,
     ):
         """Plot power spectral density, separately for each channel.
@@ -739,7 +741,9 @@ def plot_topo(
         %(fig_facecolor)s
         %(axis_facecolor)s
         %(axes_spectrum_plot_topo)s
-        %(block)s
+        block : bool | None
+            This parameter is deprecated and will be removed in MNE 1.15; blocking now
+            follows Matplotlib's behavior (see ``show``).
         %(show)s
 
         Returns
@@ -777,7 +781,16 @@ def plot_topo(
             y_label=y_label,
             axes=axes,
         )
-        plt_show(show, block=block)
+        if block is None:
+            plt_show(show)
+        else:
+            warn(
+                "The 'block' parameter is deprecated and will be removed in MNE 1.15; "
+                "blocking now follows Matplotlib's behavior. Pass show=False and call "
+                "matplotlib.pyplot.show() to control it.",
+                FutureWarning,
+            )
+            plt_show(show, block=block)
         return fig
 
     @fill_doc

mne/time_frequency/tests/test_spectrum.py

@@ -718,6 +718,8 @@ def test_plot_spectrum(method, output, average, request):
         n_bad = sum(same_color(line.get_color(), bad_color) for line in lines)
         assert n_bad == 1
     spectrum.plot_topo()
+    with pytest.warns(FutureWarning, match="'block' parameter is deprecated"):
+        spectrum.plot_topo(block=True)
     spectrum.plot_topomap()
 
 

mne/utils/docs.py

@@ -4265,7 +4265,13 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
 
 docdict["show"] = """\
 show : bool
-    Show the figure if ``True``.
+    Show the figure if ``True``. When shown, blocking follows
+    :func:`matplotlib.pyplot.show`: the call blocks until the window is closed unless
+    Matplotlib's interactive mode is on (enabled with :func:`matplotlib.pyplot.ion` or
+    IPython's ``%%matplotlib`` magic command), in which case it returns immediately.
+    Interactive mode is off by default, so a plain script or REPL blocks. Pass
+    ``show=False`` to build several figures and display them together with a single
+    :func:`matplotlib.pyplot.show` call.
 """
 
 docdict["show_names_topomap"] = """

mne/viz/raw.py

@@ -554,7 +554,7 @@ def plot_raw_psd_topo(
     fig_facecolor="k",
     axis_facecolor="k",
     axes=None,
-    block=False,
+    block=None,
     show=True,
     n_jobs=None,
     verbose=None,
@@ -587,9 +587,9 @@ def plot_raw_psd_topo(
         A matplotlib-compatible color to use for the axis background.
         Defaults to black.
     %(axes_spectrum_plot_topo)s
-    block : bool
-        Whether to halt program execution until the figure is closed.
-        May not work on all systems / platforms. Defaults to False.
+    block : bool | None
+        This parameter is deprecated and will be removed in MNE 1.15; blocking now
+        follows Matplotlib's behavior (see ``show``).
     %(show)s
     %(n_jobs)s
     %(verbose)s

mne/viz/topomap.py

@@ -2420,7 +2420,7 @@ def plot_evoked_topomap(
         interactive_colorbar=True,
         single_time_point=False,
     )
-    plt_show(show, block=False)
+    plt_show(show)
     if axes is not None:
         fig.canvas.draw()
     return fig

mne/viz/utils.py

@@ -941,7 +941,7 @@ def plot_sensors(
     ch_groups=None,
     to_sphere=True,
     axes=None,
-    block=False,
+    block=None,
     show=True,
     sphere=None,
     pointsize=None,
@@ -992,11 +992,17 @@ def plot_sensors(
     %(axes_montage)s
 
         .. versionadded:: 0.13.0
-    block : bool
-        Whether to halt program execution until the figure is closed. Defaults
-        to False.
+    block : bool | None
+        Whether to halt program execution until the figure is closed. By default
+        (``None``) this follows :func:`matplotlib.pyplot.show`: it blocks unless
+        Matplotlib's interactive mode is on (see :func:`matplotlib.pyplot.ion`), in
+        which case it returns immediately. Set to ``True`` to force blocking, which is
+        useful with ``kind="select"`` to collect the interactive selection synchronously
+        when interactive mode is on.
 
         .. versionadded:: 0.13.0
+        .. versionchanged:: 1.13
+           The default changed from ``False`` to ``None`` (follow Matplotlib).
     show : bool
         Show figure if True. Defaults to True.
     %(sphere_topomap_auto)s