FIX: resolve JupyterLite notebook install errors in CircleCI preview

- Switch piplite.install → micropip.install(..., keep_going=True) so
  the matplotlib/scipy version mismatch between Pyodide's bundled
  packages and MNE's declared minimums no longer blocks notebook startup
- Add --no-build-isolation to pip wheel so it reads the patched
  pyproject.toml from disk rather than the editable-install cache
- Wrap pyproject.toml patching in try/finally so it is always restored
  even if the wheel build crashes mid-run
- Tighten regex patterns so the relaxation covers any future bumps to
  the minimum versions in pyproject.toml (scipy>=1.1x, mpl>=3.x)
- Remove the 1.5 GB OSF sample-data download fallback; replace with a
  clear warning pointing users to the live mne.tools documentation
- Make pyodide_pooch_fetch actually raise RuntimeError for OSF URLs
  instead of just printing a message and proceeding (which caused silent
  hangs and OOM crashes in the browser)
- Tidy first_notebook_cell: remove duplicate matplotlib import,
  consolidate os import at the top of the cell

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: natinew77-creator

doc/conf.py

@@ -549,20 +549,34 @@
 with open(pyproject_path, encoding="utf-8") as f:
     orig_pyproject = f.read()
 
-# Relax constraints for Pyodide which often lags behind PyPI
-patched = re.sub(r'"scipy\s*>=\s*1\.13"', '"scipy >= 1.11"', orig_pyproject)
-patched = re.sub(r'"matplotlib\s*>=\s*3\.9"', '"matplotlib >= 3.5"', patched)
-patched = re.sub(r'"numpy\s*>=\s*1\.26,\s*<\s*3"', '"numpy >= 1.21, < 3"', patched)
-with open(pyproject_path, "w", encoding="utf-8") as f:
-    f.write(patched)
-
+# Relax constraints for Pyodide which often lags behind PyPI.
+# The wheel built here is served to the browser kernel; micropip's
+# keep_going=True means these bounds won't block install, but we also
+# relax them here so the wheel metadata is accurate for inspection.
+patched = re.sub(r'"scipy\s*>=\s*1\.1[0-9]"', '"scipy >= 1.7"', orig_pyproject)
+patched = re.sub(r'"matplotlib\s*>=\s*3\.[5-9]"', '"matplotlib >= 3.5"', patched)
+patched = re.sub(r'"numpy\s*>=\s*1\.\d+,\s*<\s*3"', '"numpy >= 1.20, < 3"', patched)
 os.environ["SETUPTOOLS_SCM_PRETEND_VERSION"] = "9999.0.1"
-subprocess.run(
-    [sys.executable, "-m", "pip", "wheel", "..", "--no-deps", "-w", dist_lite_dir],
-    check=True,
-)
-with open(pyproject_path, "w", encoding="utf-8") as f:
-    f.write(orig_pyproject)
+try:
+    with open(pyproject_path, "w", encoding="utf-8") as f:
+        f.write(patched)
+    subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "pip",
+            "wheel",
+            "..",
+            "--no-deps",
+            "--no-build-isolation",
+            "-w",
+            dist_lite_dir,
+        ],
+        check=True,
+    )
+finally:
+    with open(pyproject_path, "w", encoding="utf-8") as f:
+        f.write(orig_pyproject)
 
 jupyterlite_build_command_options = {"piplite-wheels": dist_lite_dir}
 
@@ -573,16 +587,18 @@
     },
     "first_notebook_cell": (
         "# 💡 This cell is automatically added to the start of each notebook.\n"
-        "import piplite\n"
-        "# Install mne without a version pin so piplite resolves the local\n"
-        "# dev wheel from all.json when available, and falls back cleanly to\n"
-        "# the latest stable release from PyPI in restricted preview\n"
-        "# environments (e.g. CircleCI artifact viewer) where the local index\n"
-        "# is blocked by the host's authentication proxy.\n"
-        "await piplite.install(['mne', 'scikit-learn', 'joblib'])\n"
+        "# It installs MNE and patches the browser environment for Pyodide.\n"
+        "import micropip\n"
+        "# keep_going=True lets micropip install even if Pyodide's bundled\n"
+        "# matplotlib/scipy/numpy are older than MNE's declared minimums.\n"
+        "# MNE's runtime code only checks matplotlib >= 3.7/3.8, so 3.8.4 works.\n"
+        "await micropip.install(['mne', 'scikit-learn', 'joblib'], keep_going=True)\n"
         "\n"
-        "# Mock lzma since it is missing in Pyodide but required by pooch/joblib\n"
         "import sys\n"
+        "import os\n"
+        "import io\n"
+        "\n"
+        "# Mock lzma — missing in Pyodide but imported by pooch/joblib\n"
         "import types\n"
         "class MockLZMA:\n"
         "    LZMAError = Exception\n"
@@ -594,7 +610,7 @@
         "if 'lzma' not in sys.modules:\n"
         "    sys.modules['lzma'] = MockLZMA()\n"
         "\n"
-        "# Mock multiprocessing since it is missing in Pyodide but required by joblib\n"
+        "# Mock multiprocessing — missing in Pyodide but imported by joblib\n"
         "from unittest.mock import MagicMock\n"
         "if 'multiprocessing' not in sys.modules:\n"
         "    m = MagicMock()\n"
@@ -603,74 +619,64 @@
         "    sys.modules['multiprocessing.util'] = m.util\n"
         "    sys.modules['multiprocessing.pool'] = m.pool\n"
         "\n"
-        "# 1. Patch networking so pooch can download datasets\n"
-        "import pooch\n"
+        "# Patch requests so pooch can fetch files already on /drive/mne_data.\n"
+        "# open_url works for both text and binary in Pyodide >= 0.21.\n"
         "import requests\n"
-        "import urllib.request\n"
-        "import urllib.error\n"
-        "import io\n"
-        "\n"
-        "orig_send = requests.Session.send\n"
         "import pyodide\n"
+        "orig_send = requests.Session.send\n"
         "def pyodide_send(self, request, **kwargs):\n"
         "    try:\n"
-        "        content = pyodide.http.open_url(request.url).read()\n"
+        "        buf = pyodide.http.open_url(request.url)\n"
+        "        content = buf.getvalue() if hasattr(buf, 'getvalue') else buf.read()\n"
         "        if isinstance(content, str):\n"
         "            content = content.encode('utf-8')\n"
-        "        status = 200\n"
         "    except Exception as e:\n"
-        "        print(f'pyodide.http.open_url failed for {request.url}: {e}')\n"
+        "        print(f'open_url failed for {request.url}: {e}')\n"
         "        return orig_send(self, request, **kwargs)\n"
         "    response = requests.Response()\n"
-        "    response.status_code = status\n"
+        "    response.status_code = 200\n"
         "    response.url = request.url\n"
         "    response.raw = io.BytesIO(content)\n"
         "    return response\n"
         "requests.Session.send = pyodide_send\n"
         "\n"
-        "import os\n"
+        "# Set the data directory: /drive/mne_data is pre-populated by the doc\n"
+        "# build (conf.py copies the required sample-data subset there).\n"
+        "# If absent (e.g. standalone JupyterLite), fall back to /tmp/mne_data\n"
+        "# with a clear warning — do NOT attempt to download ~1.5 GB from OSF.\n"
         "mne_data_path = (\n"
         "    '/drive/mne_data' if os.path.exists('/drive/mne_data')\n"
         "    else '/tmp/mne_data'\n"
         ")\n"
         "os.makedirs(mne_data_path, exist_ok=True)\n"
         "if mne_data_path == '/tmp/mne_data':\n"
-        "    from pyodide.http import pyfetch\n"
-        "    import tarfile\n"
-        "    sample_dir = os.path.join(mne_data_path, 'MNE-sample-data')\n"
-        "    if not os.path.exists(sample_dir):\n"
-        "        print('Downloading MNE-sample-data via pyfetch...')\n"
-        "        try:\n"
-        "            res = await pyfetch(\n"
-        "                'https://osf.io/86qa2/download?version=5'\n"
-        "            )\n"
-        "            tar_path = os.path.join(mne_data_path, 'sample.tar.gz')\n"
-        "            with open(tar_path, 'wb') as f:\n"
-        "                f.write(await res.bytes())\n"
-        "            with tarfile.open(tar_path, 'r:gz') as tar:\n"
-        "                tar.extractall(mne_data_path)\n"
-        "            os.remove(tar_path)\n"
-        "            print('MNE-sample-data extracted successfully.')\n"
-        "        except Exception as e:\n"
-        "            print(f'Failed to fetch or extract sample data: {e}')\n"
+        "    print(\n"
+        "        '⚠️  MNE sample data not found at /drive/mne_data. '\n"
+        "        'Cells that load datasets will raise FileNotFoundError. '\n"
+        "        'Open this notebook from the live MNE docs (mne.tools) '\n"
+        "        'where sample data is pre-bundled.'\n"
+        "    )\n"
         "os.environ['MNE_DATA'] = mne_data_path\n"
         "os.environ['MNE_DATASETS_SAMPLE_PATH'] = mne_data_path\n"
         "\n"
-        "# Intercept pooch to provide helpful errors for large OSF datasets\n"
+        "# Block pooch from attempting large OSF downloads in the browser.\n"
+        "# The required files are either pre-injected or unavailable.\n"
+        "import pooch\n"
         "orig_pooch_fetch = pooch.Pooch.fetch\n"
         "def pyodide_pooch_fetch(self, fname, processor=None, downloader=None):\n"
         "    url = self.get_url(fname)\n"
         "    if 'osf.io' in url or 'files.osf.io' in url:\n"
-        "        print(f'Bypassing OSF download for"
-        " {fname}. Using injected local cache.')\n"
-        "    return orig_pooch_fetch(\n"
-        "        self, fname, processor=processor, downloader=downloader\n"
-        "    )\n"
+        "        raise RuntimeError(\n"
+        "            f'Cannot download {fname!r} from OSF in JupyterLite: '\n"
+        "            'browser CORS policy and memory limits prevent large '\n"
+        "            'dataset downloads. Open this notebook from mne.tools '\n"
+        "            'where sample data is pre-bundled, or run it locally.'\n"
+        "        )\n"
+        "    return orig_pooch_fetch(self, fname, processor=processor, downloader=downloader)\n"
         "pooch.Pooch.fetch = pyodide_pooch_fetch\n"
         "\n"
-        "# 2. Patch MNEBrowseFigure to auto-display in Pyodide's inline backend\n"
+        "# Import MNE and finalize setup.\n"
         "import mne\n"
-        "import os\n"
         "try:\n"
         "    mne.get_config()\n"
         "except Exception:\n"
@@ -679,16 +685,17 @@
         "        print('Corrupted MNE config deleted automatically.')\n"
         "    except Exception:\n"
         "        pass\n"
-        "for ds in ['SAMPLE', 'TESTING', 'SSVEP',"
-        " 'EEGBCI', 'SOMATO', 'AUDIOVISUAL', 'BRAINSTORM']:\n"
+        "for ds in ['SAMPLE', 'TESTING', 'SSVEP', 'EEGBCI', 'SOMATO',\n"
+        "           'AUDIOVISUAL', 'BRAINSTORM']:\n"
         "    mne.set_config(f'MNE_DATASETS_{ds}_PATH', mne_data_path)\n"
+        "\n"
+        "# Switch matplotlib to inline so figures render in the notebook.\n"
         "import IPython\n"
         "IPython.get_ipython().run_line_magic('matplotlib', 'inline')\n"
         "import matplotlib.pyplot as plt\n"
         "import importlib\n"
         "viz_utils = importlib.import_module('mne.viz.utils')\n"
         "orig_plt_show = viz_utils.plt_show\n"
-        "import matplotlib.pyplot as plt\n"
         "def pyodide_plt_show(*args, **kwargs):\n"
         "    orig_plt_show(*args, **kwargs)\n"
         "    import IPython.display\n"