Simplify doc building with more refleak (#14045)

Author: larsoner

doc/sphinxext/mne_doc_utils.py

@@ -15,16 +15,21 @@
 import numpy as np
 import pyvista
 import sphinx.util.logging
-from refleak.testing import assert_no_instances
+from refleak.testing import Snapshot, assert_no_instances, gc_collect_once
 from sphinx.errors import ExtensionError
 
 import mne
-from mne.utils import Bunch, _get_extra_data_path, sizeof_fmt
+from mne.utils import Bunch, _get_extra_data_path, _is_vtk, sizeof_fmt
 from mne.viz import Brain
 
 sphinx_logger = sphinx.util.logging.getLogger("mne")
 _np_print_defaults = np.get_printoptions()
 
+# Taken at each example's "before" reset and diffed at its "after" reset, so
+# any VTK object an example creates but fails to release is flagged -- not
+# just the specific classes checked by name below.
+_vtk_snapshot = None
+
 
 def reset_warnings(gallery_conf, fname):
     """Ensure we are future compatible and ignore silly warnings."""
@@ -148,10 +153,6 @@ def reset_modules(gallery_conf, fname, when):
         from pyvistaqt import BackgroundPlotter  # noqa
     except ImportError:
         BackgroundPlotter = None  # noqa
-    try:
-        from vtkmodules.vtkCommonDataModel import vtkPolyData  # noqa
-    except ImportError:
-        vtkPolyData = None  # noqa
     try:
         from mne_qt_browser._pg_figure import MNEQtBrowser
     except ImportError:
@@ -187,6 +188,9 @@ def reset_modules(gallery_conf, fname, when):
         IPython.core.completer.__main__ = sys.modules["__main__"]
     except Exception:
         pass
+    # A plain collect (not the deduped one): dead figures must drop out of
+    # ui_events._event_channels (a WeakKeyDictionary) before the emptiness
+    # assert below.
     gc.collect()
 
     # Agg does not call close_event so let's clean up on our own :(
@@ -198,25 +202,16 @@ def reset_modules(gallery_conf, fname, when):
     orig_when = when
     when = f"mne/conf.py:Resetter.__call__:{when}:{fname}"
     # Support stuff like
-    # MNE_SKIP_INSTANCE_ASSERTIONS="Brain,Plotter,BackgroundPlotter,vtkPolyData,_Renderer" make html-memory  # noqa: E501
+    # MNE_SKIP_INSTANCE_ASSERTIONS="Brain,Plotter,BackgroundPlotter,vtk,_Renderer" make html-memory  # noqa: E501
     # to just test MNEQtBrowser
     skips = os.getenv("MNE_SKIP_INSTANCE_ASSERTIONS", "").lower()
     prefix = ""
     request = Bunch()  # just give it something to say "we have done GC already"
     request.node = Bunch()
+    global _vtk_snapshot
     if skips not in ("true", "1", "all"):
         prefix = "Clean "
         skips = skips.split(",")
-        if "brain" not in skips:
-            assert_no_instances(Brain, when=when, request=request)
-        if Plotter is not None and "plotter" not in skips:
-            assert_no_instances(Plotter, when=when, request=request)
-        if BackgroundPlotter is not None and "backgroundplotter" not in skips:
-            assert_no_instances(BackgroundPlotter, when=when, request=request)
-        if vtkPolyData is not None and "vtkpolydata" not in skips:
-            assert_no_instances(vtkPolyData, when=when, request=request)
-        if "_renderer" not in skips:
-            assert_no_instances(_Renderer, when=when, request=request)
         if MNEQtBrowser is not None and "mneqtbrowser" not in skips:
             # Ensure any manual fig.close() events get properly handled
             from mne_qt_browser._pg_figure import QApplication
@@ -225,7 +220,36 @@ def reset_modules(gallery_conf, fname, when):
             if inst is not None:
                 for _ in range(2):
                     inst.processEvents()
-            assert_no_instances(MNEQtBrowser, when=when, request=request)
+        # This collect must come AFTER _cleanup_agg() above: an example's
+        # subscribed ui-events callback can be the last anchor of its whole
+        # object graph (channel dict -> callback -> __globals__ -> figures),
+        # and only cleanup breaks that loop. It is the once-per-reset collect
+        # that the checks below dedupe against (see gc_collect_once).
+        gc_collect_once(request)
+        objs = gc.get_objects()  # scan the heap once, share across all checks
+        if "brain" not in skips:
+            assert_no_instances(Brain, when=when, request=request, objs=objs)
+        if Plotter is not None and "plotter" not in skips:
+            assert_no_instances(Plotter, when=when, request=request, objs=objs)
+        if BackgroundPlotter is not None and "backgroundplotter" not in skips:
+            assert_no_instances(
+                BackgroundPlotter, when=when, request=request, objs=objs
+            )
+        if "_renderer" not in skips:
+            assert_no_instances(_Renderer, when=when, request=request, objs=objs)
+        if MNEQtBrowser is not None and "mneqtbrowser" not in skips:
+            assert_no_instances(MNEQtBrowser, when=when, request=request, objs=objs)
+        if "vtk" not in skips:
+            # Diff all VTK objects across each example: catches leaks of any
+            # VTK class (actors, mappers, arrays, ...), not just the specific
+            # classes above, while tolerating VTK state that legitimately
+            # pre-dates the example.
+            if orig_when == "after" and _vtk_snapshot is not None:
+                _vtk_snapshot.assert_no_new(when=when, request=request, objs=objs)
+            _vtk_snapshot = None
+            if orig_when == "before":
+                _vtk_snapshot = Snapshot(_is_vtk, label="VTK", objs=objs)
+        del objs
     # This will overwrite some Sphinx printing but it's useful
     # for memory timestamps
     if os.getenv("SG_STAMP_STARTS", "").lower() == "true":

mne/conftest.py

@@ -22,7 +22,7 @@
 import pytest
 from packaging.version import Version
 from pytest import StashKey, register_assert_rewrite
-from refleak.testing import assert_no_instances, gc_collect_once
+from refleak.testing import Snapshot, assert_no_instances, gc_collect_once
 
 # Any `assert` statements in our testing functions should be verbose versions
 register_assert_rewrite("mne.utils._testing")
@@ -41,6 +41,7 @@
     Bunch,
     _check_qt_version,
     _chmod_rw_R,
+    _is_vtk,
     _pl,
     _record_warnings,
     _TempDir,
@@ -1077,36 +1078,34 @@ def brain_gc(request):
         return
     from mne.viz import Brain
 
-    ignore = set(id(o) for o in gc.get_objects())
-    vtk_ignores = ("vtkBuffer_IhE",)
+    # Snapshot stores only ids (pins nothing alive) so VTK objects that
+    # pre-date the test (e.g. held by module-level state) are never reported.
+    snap = Snapshot(_is_vtk, label="VTK")
     yield
     close_func()
+    # pyvistaqt >= 0.11.3 schedules the plotter's window for deferred deletion
+    # (deleteLater) on close; until Qt processes it, the C++ window object
+    # keeps its Python wrapper (and thereby the whole plotter graph) alive.
+    from qtpy.QtCore import QEvent
+    from qtpy.QtWidgets import QApplication
+
+    app = QApplication.instance()
+    if app is not None:
+        for _ in range(2):
+            app.processEvents()
+            app.sendPostedEvents(None, QEvent.DeferredDelete)
     if not _test_passed(request):
         return
+    # The collect must happen *before* list(Brain._instances) is evaluated:
+    # a Brain in a dead reference cycle is still in the WeakSet until
+    # collected, and the list would pin it alive and falsely report it.
     gc_collect_once(request)
     # Brain._instances is a WeakSet populated only when MNE_3D_BACKEND_TESTING
     # is set (see Brain.__init__), so use it instead of a slow gc.get_objects()
     # scan of the whole process to check for lingering Brain instances.
     assert_no_instances(Brain, "after", request=request, objs=list(Brain._instances))
-    # Check VTK -- these aren't individually tracked, so we still need a full
-    # heap scan here.
-    objs = gc.get_objects()
-    bad = list()
-    for o in objs:
-        try:
-            name = o.__class__.__name__
-        except Exception:  # old Python, probably
-            pass
-        else:
-            if (
-                name.startswith("vtk")
-                and name not in vtk_ignores
-                and id(o) not in ignore
-            ):
-                bad.append(name)
-        del o
-    del objs, ignore, Brain
-    assert len(bad) == 0, "VTK objects linger:\n" + "\n".join(bad)
+    # VTK objects aren't individually tracked, so this one is a full heap scan.
+    snap.assert_no_new("after", request=request)
 
 
 _files = list()
@@ -1316,12 +1315,21 @@ def nirx_snirf(request):
 def qt_windows_closed(request, qapp):
     """Ensure that no new Qt windows are open after a test."""
     _check_skip_backend("pyvistaqt")
-    qapp.processEvents()
+    from qtpy.QtCore import QEvent
+
+    # pyvistaqt >= 0.11.3 deletes plotter windows via deleteLater on close;
+    # processEvents alone never dispatches those DeferredDelete events, so
+    # drain them symmetrically before counting and before re-counting (a
+    # pending deletion from an earlier test must not inflate n_before)
+    for _ in range(2):
+        qapp.processEvents()
+        qapp.sendPostedEvents(None, QEvent.DeferredDelete)
     gc.collect()
     n_before = len(qapp.topLevelWidgets())
     yield
     for _ in range(2):
         qapp.processEvents()
+        qapp.sendPostedEvents(None, QEvent.DeferredDelete)
     gc.collect()
     # Don't check when the test fails
     if not _test_passed(request):

mne/utils/__init__.pyi

@@ -87,6 +87,7 @@ __all__ = [
     "_import_nibabel",
     "_import_pymatreader_funcs",
     "_is_numeric",
+    "_is_vtk",
     "_julian_to_date",
     "_mask_to_onsets_offsets",
     "_on_missing",
@@ -207,6 +208,7 @@ from ._testing import (
     ArgvSetter,
     _chmod_rw_R,
     _click_ch_name,
+    _is_vtk,
     _raw_annot,
     _TempDir,
     assert_and_remove_boundary_annot,

mne/utils/_testing.py

@@ -438,3 +438,25 @@ def copytree_rw(src, dst):
     shutil.copytree(src, dst)
     _chmod_rw_R(dst)
     return dst
+
+
+_vtk_object_base = None
+
+
+def _is_vtk(obj):
+    """Check if an object is a VTK object worth leak-checking (for refleak).
+
+    An ``isinstance`` check, not a class-name-prefix one: VTK >= 9.6
+    instantiates pythonic override subclasses whose names lack the ``vtk``
+    prefix (``PolyData``, ``VTKAOSArray_vtkFloatArray``, ...), and pyvista
+    wrapper subclasses count as VTK objects too. Requires ``vtkmodules``.
+    """
+    global _vtk_object_base
+    if _vtk_object_base is None:
+        from vtkmodules.vtkCommonCore import vtkObjectBase
+
+        _vtk_object_base = vtkObjectBase
+    # vtkBuffer_IhE (vtkBuffer<unsigned char>) instances are known to linger
+    return (
+        isinstance(obj, _vtk_object_base) and obj.__class__.__name__ != "vtkBuffer_IhE"
+    )

mne/viz/backends/_qt.py

@@ -28,7 +28,7 @@
     # non-object-based-abstraction-only, remove
     Signal,
 )
-from qtpy.QtGui import QCursor, QIcon, QKeyEvent
+from qtpy.QtGui import QCursor, QGuiApplication, QIcon, QKeyEvent
 from qtpy.QtWidgets import (
     QButtonGroup,
     QCheckBox,
@@ -1528,7 +1528,13 @@ def _window_close_disconnect(self, after=True):
             self._window_before_close_callbacks.clear()
 
     def _window_get_dpi(self):
-        return self._window.windowHandle().screen().logicalDotsPerInch()
+        # windowHandle() is None until the window is realized (e.g. when the
+        # figure has not been shown yet), so fall back to the primary screen
+        handle = self._window.windowHandle()
+        screen = None if handle is None else handle.screen()
+        if screen is None:
+            screen = QGuiApplication.primaryScreen()
+        return screen.logicalDotsPerInch()
 
     def _window_get_size(self):
         w = self._interactor.geometry().width()

pyproject.toml

@@ -23,7 +23,7 @@ doc = [
   "pyvistaqt >= 0.11",  # released 2023-06-30, will become 0.12 on 2028-07-01
   "pyxdf",
   "pyzmq != 24.0.0",
-  "refleak",
+  "refleak >=0.2.1",
   "scikit-learn >= 1.5",  # released 2024-05-21, will become 1.6 on 2026-12-09
   "seaborn >= 0.5, != 0.11.2",
   "selenium >= 4.27.1",
@@ -54,7 +54,7 @@ test = [
   "pytest-qt >= 4.3",
   "pytest-rerunfailures",
   "pytest-timeout >= 2.2",
-  "refleak",
+  "refleak >=0.2.1",
   "ruff >= 0.1",
   "twine",
   "vulture",

tools/install_pre_requirements.sh

@@ -20,22 +20,23 @@ python -m pip install $STD_ARGS pip setuptools packaging \
 	patsy pytz tzdata nibabel tqdm trx-python joblib numexpr \
 	"$MNE_QT_BACKEND!=6.9.1" \
 	py-cpuinfo blosc2 hatchling "formulaic>=1.1.0" \
-	matplotlib
+	scikit-learn
 python -m pip uninstall -yq numpy
 echo "::endgroup::"
 echo "::group::Scientific Python Nightly Wheels"
 python -m pip install $STD_ARGS --only-binary ":all:" --default-timeout=60 \
 	--index-url "https://pypi.anaconda.org/scientific-python-nightly-wheels/simple" \
 	"numpy>=2.5.0.dev0" \
 	"scipy>=1.18.0.dev0" \
-	"scikit-learn>=1.9.dev0" \
 	"pandas>=3.1.0.dev0" \
 	"dipy>=1.12.0.dev0" \
 	"tables>=3.10.3.dev0" \
 	"pyarrow>=22.0.0.dev0" \
 	"matplotlib>=3.11.0.dev0" \
 	"statsmodels>=0.15.0.dev0" \
 	"h5py>=3.13.0"
+# https://github.com/scikit-learn/scikit-learn/issues/34458
+#	"scikit-learn>=1.9.dev0" \
 echo "::endgroup::"
 # No Numba because it forces an old NumPy version
 
@@ -47,7 +48,7 @@ echo "::endgroup::"
 echo "::group::Everything else"
 python -m pip install $STD_ARGS \
 	"pyvista @ https://github.com/pyvista/pyvista/archive/refs/heads/main.zip" \
-	"pyvistaqt @ https://github.com/pyvista/pyvistaqt/archive/refs/heads/main.zip" \
+	"pyvistaqt @ https://github.com/larsoner/pyvistaqt/archive/refs/heads/qvtk-opengl-widget.zip" \
 	"git+https://github.com/nilearn/nilearn" \
 	"git+https://github.com/pierreablin/picard" \
 	"git+https://github.com/the-siesta-group/edfio" \

tools/pylock.ci-old.toml

@@ -430,9 +430,9 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93e
 
 [[packages]]
 name = "refleak"
-version = "0.1.1"
-sdist = { url = "https://files.pythonhosted.org/packages/48/3d/b1fe0b6bd9fccf9666c40beafff4e042c5f83eaa54d5408ccc5559e782be/refleak-0.1.1.tar.gz", upload-time = 2026-07-04T00:57:10Z, size = 17584, hashes = { sha256 = "05c7ec81497c6f0dd80028fb933136a7d9b055a978f74b17f8bc787e1602b764" } }
-wheels = [{ url = "https://files.pythonhosted.org/packages/50/fe/b26d9cad0eb21bbbaf345b9543eabc7c28f093ed022a4df9b3027df54bcd/refleak-0.1.1-py3-none-any.whl", upload-time = 2026-07-04T00:57:09Z, size = 11937, hashes = { sha256 = "aafe8c1141b59df7c10eaa9bdf509ddefcf00624be644118adb678c4af30c38f" } }]
+version = "0.2.1"
+sdist = { url = "https://files.pythonhosted.org/packages/8a/70/b586bac19d443491b0b1bf18e017c98dfdb190503022e58afeb6240ee64f/refleak-0.2.1.tar.gz", upload-time = 2026-07-10T12:59:14Z, size = 28367, hashes = { sha256 = "8dd9585634375b0c0e1e9be12f6cf699b97f140c9a615c5c75b4fdb2305e0849" } }
+wheels = [{ url = "https://files.pythonhosted.org/packages/2c/e9/0818313965cdfd38f8639e6ac51d50c1bab20c42dfb8e1de571cf4553105/refleak-0.2.1-py3-none-any.whl", upload-time = 2026-07-10T12:59:13Z, size = 20801, hashes = { sha256 = "e48a7c54523273ec99adff87a83a88fddb52f21778a0479190425fcc456ab5a3" } }]
 
 [[packages]]
 name = "requests"

tools/vulture_allowlist.py

@@ -24,6 +24,7 @@
 mpl_backend
 recwarn
 pytestmark
+_is_vtk
 nbexec
 disabled_event_channels
 ch_subset_adjacency