Repository navigation
Record that the browser runtime is its own package - #1458
Merged
Merged
Conversation
The measurements that drove this are in sccn/eegprep#395 and the decision was argued more than once, most recently against the plan to move mne, pybids, h5py and neo into eegprep extras. It closes that path, so it belongs in an ADR rather than in a comment thread. The finding that settled it: an import-site audit cannot tell which dependencies are safe to move. eeglabio has no import site anywhere in eegprep and is not removable, because mne imports it when asked to write an EEGLAB file, which 12 tests proved on every supported platform after it was removed.
📦 Package PreviewYour package is ready to test! bun install -g nemar-cli@PR1458Version: 🤖 Updated on each push. |
This was referenced Sep 20, 2026
eegprep[lean] is the name everyone reaches for first, and it cannot work: a Python extra adds to a distribution's requirements and never replaces them, so pip and micropip both resolve eegprep's whole base install before the extra is considered. A small install needs a distribution whose base is small. Recording the reason in the ADR because it is the proposal that will come back. The lean distribution is published from the eegprep repository rather than a new one, and eegprep depends on it, so the science code is not forked and the default install stays a superset of what it is today. Its tiers are extras, which is what extras are for, since each one genuinely adds to the tier beneath it: 4.2 MB to read a window, plot adding matplotlib at 14.0 MB, preprocess adding scipy at 30.4 MB, ica adding python-picard at 36.3 MB. Plotting is out of the base deliberately; it is 9.8 MB and it arrives when a plot is asked for.
matplotlib is 62 percent bundled fonts and its working library is about 2 MB, so a rebuilt wheel is technically available. Costed out it saves 2.47 MB without changing behavior, which does not pay for a wheel to maintain against every matplotlib release and a font-fallback divergence to declare. Recorded with the threshold that would change the answer, around 8 MB or half the tier, so the next person finds the measurement instead of repeating it.
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds ADR 0069, and closes a path this epic had been walking down.
What was decided
eegprep stays whole. Its default install keeps every dependency it has today, so
pip install eegprepis unchanged and no existing user gets less than they had.The browser runtime becomes a separate distribution,
eegprep-lean, published from the eegprep repository rather than a new one: same source tree, same tests, same maintainers. eegprep depends on it and re-exports it, so the default install is a superset of what it is today and the science code is not forked into two copies that drift. This project owns the seam: a declared contract, with any divergence in behavior written into that contract rather than discovered by a user who hit it.Why not
eegprep[lean]It is the name everyone reaches for first, including in the discussion that produced this ADR, and it cannot work. A Python extra adds to a distribution's requirements and never replaces them, so
pip install eegprep[lean]resolves eegprep's whole 62.6 MB base and then adds more. micropip resolves the same way, so the browser gets no relief either. A genuinely small install needs a distribution whose base is small: either a lean eegprep, which changes what every existing user gets from an unchanged command, or a second name. The ADR records this in full, because it is the proposal that will come back.Extras are still the right mechanism one level down, where they are additive by nature:
eegprep-leaneegprep-lean[plot]eegprep-lean[preprocess]eegprep-lean[ica]Plotting is out of the base deliberately. It costs 9.8 MB and it is the first thing a person asks for after looking at data, so it arrives when a plot is actually asked for rather than being paid for by a session that only reads.
Why it is an ADR rather than a comment
It closes off the alternative, which had measurements behind it and was nearly executed. The plan was to move mne, pybids, h5py and neo into eegprep extras, taking the base install from 61 packages and 62.6 MB down toward 36.3 MB.
Two findings stopped it:
pip install eegprepgives people, not merely when it loads things.eeglabiohas no import site anywhere insrc/and is still load-bearing: mne imports it when asked to write an EEGLAB file, andeeg_mne2eegexports through mne. Removing it failed 12 tests on every supported platform. Every other candidate would need the same proof, run against an environment that genuinely lacks the package.The honest cost is written into the ADR: a seam, and seams drift. Two implementations of one operation can disagree, and that disagreement shows up as a result that differs between a browser and a workstation. The contract is the deliverable for exactly that reason. Divergence is allowed; undeclared divergence is not.
Related work
phase/374-extras-splitis already inepic/324-pyodide-browserand moved oct2py, psutil and pyedflib out of the base install. That work stands; this decision is about where the line stops.Numbered 0069 rather than 0068: 0068 was taken on
devwhile this was being written.