refactor: cache the static-export probe instead of a module global

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: larsoner

plotly/io/_sg_scraper.py

@@ -126,39 +126,35 @@ def _trailing_repr_figure(block, block_vars):
     return figure
 
 
-# Whether static image export works at all, probed on the first scrape so
-# that a build without Kaleido or a browser warns once (per worker, for
-# parallel sphinx-gallery builds) instead of once per figure.
-_export_available = None
-
-
+@functools.lru_cache(maxsize=None)  # functools.cache needs Python 3.9
 def _static_export_available():
-    global _export_available
-    if _export_available is None:
+    """Whether static image export works, probed on the first scrape.
+
+    Cached so that a build without Kaleido or a browser warns once (per
+    worker, for parallel sphinx-gallery builds) instead of once per figure.
+    """
+    try:
+        plotly.io.to_image({"data": []}, format="png", validate=False)
+    except Exception as exc:
         try:
-            plotly.io.to_image({"data": []}, format="png", validate=False)
-        except Exception as exc:
-            _export_available = False
-            try:
-                from sphinx.util.logging import getLogger
-
-                warn = functools.partial(
-                    getLogger(__name__).warning, type="plotly", subtype="sg_scraper"
-                )
-            except Exception:
-                warn = logging.getLogger(__name__).warning
-            warn(
-                "plotly static image export is unavailable, so example "
-                "thumbnails will fall back to a placeholder image. Static "
-                "export requires Kaleido and a Chromium-based browser; see "
-                "https://plotly.com/python/static-image-export/ for "
-                "installation instructions. The failure was: %s: %s",
-                type(exc).__name__,
-                exc,
+            from sphinx.util.logging import getLogger
+
+            warn = functools.partial(
+                getLogger(__name__).warning, type="plotly", subtype="sg_scraper"
             )
-        else:
-            _export_available = True
-    return _export_available
+        except Exception:
+            warn = logging.getLogger(__name__).warning
+        warn(
+            "plotly static image export is unavailable, so example "
+            "thumbnails will fall back to a placeholder image. Static "
+            "export requires Kaleido and a Chromium-based browser; see "
+            "https://plotly.com/python/static-image-export/ for "
+            "installation instructions. The failure was: %s: %s",
+            type(exc).__name__,
+            exc,
+        )
+        return False
+    return True
 
 
 def _inline_html(fig_dict):

tests/test_io/test_sg_scraper.py

@@ -75,8 +75,9 @@ def gallery(tmp_path, monkeypatch):
     # is imported, which may have happened in another test already.
     monkeypatch.setattr(pio.renderers, "default", "sphinx_gallery_png")
     monkeypatch.setattr(pio, "write_image", dummy_image_writer())
-    # Images come from the stand-in above, so skip the Kaleido probe.
-    monkeypatch.setattr(sg_scraper, "_export_available", True)
+    # Images come from the stand-in above, so the Kaleido probe must pass too
+    monkeypatch.setattr(pio, "to_image", lambda *args, **kwargs: b"")
+    sg_scraper._static_export_available.cache_clear()
 
     example_dir = tmp_path / "auto_examples"
     thumb_dir = example_dir / "images" / "thumb"
@@ -114,6 +115,7 @@ def thumbnail(**file_conf):
         thumbnail=thumbnail,
     )
     del sphinx_gallery_figures[:]
+    sg_scraper._static_export_available.cache_clear()
 
 
 @pytest.mark.parametrize("image_format", ["png", "svg"])
@@ -222,7 +224,7 @@ def raise_no_browser(*args, **kwargs):
         raise ValueError("no browser")
 
     monkeypatch.setattr(pio, "to_image", raise_no_browser)
-    monkeypatch.setattr(sg_scraper, "_export_available", None)
+    sg_scraper._static_export_available.cache_clear()
     fig = go.Figure(data=[go.Scatter(x=[1, 2, 3], y=[3, 2, 1])])
     pio.show(fig)
     gallery.globals["___"] = fig