Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,9 @@ Please report problems at https://github.com/kovirlabs/nu/issues.
Nu Ran**), **Plugins** and **Select Language**.
* Nu removes the copy of Python an earlier version of Nu unpacked for your
programs' environment (about 70 MB each) once nothing uses it, instead of
keeping every one after each upgrade. It unpacks that Python into a
keeping every one after each upgrade. Nu always uses the uv it comes
with, not one you installed yourself, which might be too old for it (set
`MU_UV` to choose another). It unpacks that Python into a
shorter folder (`cpython-3.12.16-20261110`, not the archive's full name),
leaving more room under Windows' 260-character path limit.
* The REPL's Jupyter kernel is registered inside your programs' environment
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ Mu is a **modal editor**: a fixed core of always-available features, plus a set

- **`mu/modes/`** — every mode subclasses **`BaseMode`** in `modes/base.py` (MicroPython-family modes subclass `MicroPythonMode`, which adds REPL/serial plumbing). A mode declares `name`, `description`, `icon`, and implements `actions()` (toolbar buttons), `api()` (autocomplete/calltip data), `workspace_dir()`, etc.; `uses_user_environment` (admin dialog env/packages tabs), `ensure_workspace_assets(wd)` (called the first time the mode is used in a session) and `star_imports` (module -> names its `import *` brings in, for Check) replace what used to be hardcoded per mode name — the core must not name plugin modes. New modes should be plugins (`docs/plugins.md`, template `plugins/example/`); a core mode is registered in `app.py` and `modes/__init__.py`. `modes/api/` holds generated API stubs (excluded from ruff, as are `plugins/*/nu_*/api`).

- **`mu/virtual_environment.py`** — Mu manages a **separate "user" virtualenv** (the `venv` singleton at module bottom) into which it installs third-party packages requested from the UI, isolated from Mu's own environment. Since Phase 4a it is driven by **uv**: `find_uv()` locates the binary (`MU_UV` → `uv` on `PATH` → the bundled `uv` wheel), `create_venv` builds it from the CPython bundled in installers (`mu/wheels/python/`, extracted once by `ensure_bundled_python` into `DATA_DIR/python/`; builds an upgrade left behind are deleted at startup by `remove_old_bundled_pythons` unless the env's `pyvenv.cfg` points into them) with `--seed --no-index`, so first launch is offline (dev checkouts without the bundle fall back to `uv venv --python <X.Y> --seed`), `Uv` wraps `uv pip`/`uv run` via `QProcess`, and `activation_vars()` activates the env for spawned user code (Run and the Jupyter kernel). Since Phase 4b (part 1) the env is **visible**: every uv command goes through `Uv` (`run_blocking`/`run`/`run_subprocess`/`script_command`), which records it in the GUI-free `mu/command_log.py` ("What Nu ran" on the admin dialog's Environment tab, and INFO in the log) — don't call uv around it; the status bar shows `Environment: <name> · Python X.Y` in modes with `uses_user_environment`; and `mu/script_metadata.py` (PEP 723) makes the Python 3 Run use `uv run --python <env python> --script <file>` for files with a `# /// script` block (see `docs/environment.md`). Bundled wheels live in `mu/wheels/` (`python -m mu.wheels --package` fetches them for installers): `wheels.baseline_packages()` = the core's `mode_packages` (ipykernel) + each installed plugin's `learner-env` extra, read from package metadata (`plugin_packages()`), never by importing the plugin.
- **`mu/virtual_environment.py`** — Mu manages a **separate "user" virtualenv** (the `venv` singleton at module bottom) into which it installs third-party packages requested from the UI, isolated from Mu's own environment. Since Phase 4a it is driven by **uv**: `find_uv()` locates the binary (`MU_UV` → Nu's own `uv` wheel, a version it needs → `uv` on `PATH`), `create_venv` builds it from the CPython bundled in installers (`mu/wheels/python/`, extracted once by `ensure_bundled_python` into `DATA_DIR/python/`; builds an upgrade left behind are deleted at startup by `remove_old_bundled_pythons` unless the env's `pyvenv.cfg` points into them) with `--seed --no-index`, so first launch is offline (dev checkouts without the bundle fall back to `uv venv --python <X.Y> --seed`), `Uv` wraps `uv pip`/`uv run` via `QProcess`, and `activation_vars()` activates the env for spawned user code (Run and the Jupyter kernel). Since Phase 4b (part 1) the env is **visible**: every uv command goes through `Uv` (`run_blocking`/`run`/`run_subprocess`/`script_command`), which records it in the GUI-free `mu/command_log.py` ("What Nu ran" on the admin dialog's Environment tab, and INFO in the log) — don't call uv around it; the status bar shows `Environment: <name> · Python X.Y` in modes with `uses_user_environment`; and `mu/script_metadata.py` (PEP 723) makes the Python 3 Run use `uv run --python <env python> --script <file>` for files with a `# /// script` block (see `docs/environment.md`). Bundled wheels live in `mu/wheels/` (`python -m mu.wheels --package` fetches them for installers): `wheels.baseline_packages()` = the core's `mode_packages` (ipykernel) + each installed plugin's `learner-env` extra, read from package metadata (`plugin_packages()`), never by importing the plugin.

- **`mu/plugin/`** — the public, versioned **plugin API** (Phase 5a; currently **0.5**, see `docs/plugins.md`): `PLUGIN_API_VERSION`, `Plugin` (`name`, `description`)/`ModePlugin` (+ `images`), `Mode` (= `BaseMode`), `MicroPythonMode`, `Device` (= `mu.logic.Device`), and the `Host` façade plugins use instead of `Editor`/`Window` (incl. `register_images`, `save_current`, `run_program`/`stop_program`, `update_action`, `python_apis`, `shared_apis`, `plotter_available`, and since 0.5 `log_command`, `current_device`, `data_dir`). Plugin images are searched after the core's by `mu.resources` (`register_image_dir`; a name clash raises, so the plugin is skipped). `app.setup_modes` registers the built-in modes through a `Host`, then `mu/plugin/loader.py` loads every enabled plugin found via entry points (group `mu.plugins`) or the drop-in folder `DATA_DIR/plugins/`, skipping (and logging) any that fail, with a `PluginRecord` each (`kind` bundled/package/folder — `loader.BUNDLED_DISTRIBUTIONS` must match the bundled `nu-*` deps — `problem`, `detail`) on `host.plugin_records`; `settings["disabled_plugins"]` switches plugins off (user settings are autosaved, and `set_plugin_enabled` saves at once). The admin dialog's **Plugins** tab (`dialogs.PluginsWidget`) shows `Host.describe_plugins()` and switches plugins from the next start via `Host.set_plugin_enabled` (the `Editor` reaches the Host as `editor.plugin_host`; no live unloading). Since Phase 5d learners also **add plugins** there (**Add a plugin…** by PyPI name, **Add from a file…** for a `.whl`, **Update**/**Remove** for ones they added): the GUI-free `mu/plugin/plugin_env.py` keeps them in `DATA_DIR/plugin-env` (made with Nu's own Python; `plugin-env.json` records its X.Y and what was added), which `app.setup_modes` puts on `sys.path` *after* Nu's entries before `load_plugins` (not if made with another Python: the tab offers **Reinstall my plugins**); its plugins are `kind` "added". Every install goes through `Uv` with `--excludes` listing every distribution Nu has (so never a second PyQt6; uv ≥ 0.9.8), then a plugin without a `mu.plugins` entry point or needing another version of something Nu has is uninstalled; its `learner-env` extra goes into the learner env. These are core-only `Host` methods (`add_plugin`, `remove_plugin`, …), not plugin API. Plugin errors never crash Nu: `mu/plugin/errors.py` guards a plugin mode's core-called methods, and `app.excepthook` / `app.thread_excepthook` (threads) hand plugin tracebacks to it first (dialog + log, rate limited, reported on the GUI thread, offer to switch off, marked in `plugins_switched_off_after_errors`); plugins raise `mu.plugin.PluginError` for expected, learner-fixable problems. Tests redirect the drop-in folder to a temp dir and reset the active error handler (autouse fixtures in the root `conftest.py`). `plugins/example/` is the template plugin; `plugins/pygamezero/` and `plugins/circuitpython/` (a `MicroPythonMode` with its own `adafruit-board-toolkit` dependency) the reference bundled plugins. Keep `mu.plugin`'s surface deliberate: anything exported there is a promise to plugin authors.

Expand Down
5 changes: 4 additions & 1 deletion docs/environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,10 @@ open the **Environment** tab, which shows:
- **Python**: the Python program inside it that runs your code.
- **Activate it**, **Add a package** and **Run a program**: the commands to do
the same things yourself in a terminal (see below).
- **Nu's uv**: where the copy of `uv` that Nu uses is.
- **Nu's uv**: where the copy of `uv` that Nu uses is. Nu uses the one it
comes with, even if you've installed uv yourself (yours may be too old for
what Nu asks of it). To make Nu use a different one, set the `MU_UV`
environment variable to its full path before starting Nu.

Each has a **Copy** button.

Expand Down
4 changes: 3 additions & 1 deletion docs/packaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,9 @@ demand).
into the bundle by Briefcase from `[tool.briefcase.app.mu].requires`.
- A pinned **`uv`** binary — it rides in via the PyPI `uv` wheel, and
`find_uv()` locates it at runtime through `uv.find_uv_bin()` (no `PATH` or
`MU_UV` needed in the packaged app).
`MU_UV` needed in the packaged app). It's preferred to a `uv` on the
learner's `PATH`, which may be older than Nu needs (`uv>=0.9.8`); `MU_UV`
still overrides both.
- The bundled plugins (`plugins/pygamezero`, `plugins/circuitpython`),
installed by Briefcase from wheels built from the checkout
(`build/plugin-wheels/`, see [above](#bundled-plugins-the-uv-workspace)).
Expand Down
24 changes: 14 additions & 10 deletions mu/virtual_environment.py
Original file line number Diff line number Diff line change
Expand Up @@ -538,10 +538,10 @@ def _uv_from_package():

The ``uv`` wheel (a runtime dependency) bundles the executable and exposes
its location via ``uv.find_uv_bin()``. In a Briefcase-packaged app this is
the binary's home: there's no system ``uv`` on ``PATH`` and ``MU_UV`` isn't
set, but the wheel is installed into the app, so this resolves it without
any path plumbing. Returns ``None`` if the package isn't importable or the
binary it points at is missing (e.g. a dev checkout using a standalone uv).
the binary's home (the wheel is installed into the app), so this resolves
it without any path plumbing, whatever uv the learner has elsewhere.
Returns ``None`` if the package isn't importable or the binary it points
at is missing (e.g. an environment installed without it).
"""
try:
import uv as uv_package
Expand All @@ -560,9 +560,13 @@ def canonical_package_name(name):
def find_uv():
"""Locate the `uv` executable.

Resolution order: the ``MU_UV`` override → a ``uv`` on the ``PATH`` (dev
checkouts, and lets a user supply their own) → the binary bundled by the
PyPI ``uv`` package (the packaged-app path, see :func:`_uv_from_package`).
Resolution order: the ``MU_UV`` override (to use another uv on purpose)
→ the binary of the PyPI ``uv`` package, Nu's own dependency (in the
installers and in a checkout's environment; see
:func:`_uv_from_package`) → a ``uv`` on the ``PATH``, only if Nu has
none of its own. Nu's own comes first because it's a version Nu needs
(``uv>=0.9.8``, for ``uv pip install --excludes``): a learner may have an
older uv on their ``PATH``.
Raise :class:`UvNotFound` if none of these is available.
"""
override = os.environ.get(UV_ENV_VAR)
Expand All @@ -572,12 +576,12 @@ def find_uv():
raise UvNotFound(
"%s points at a non-existent uv executable: %s" % (UV_ENV_VAR, override)
)
found = shutil.which("uv")
if found:
return found
bundled = _uv_from_package()
if bundled:
return bundled
found = shutil.which("uv")
if found:
return found
raise UvNotFound(
"Could not find a `uv` executable on PATH, via the %s "
"environment variable, or bundled with the `uv` package" % UV_ENV_VAR
Expand Down
32 changes: 20 additions & 12 deletions tests/virtual_environment/test_uv.py
Original file line number Diff line number Diff line change
Expand Up @@ -45,25 +45,33 @@ def test_find_uv_env_var_missing_file(tmp_path):
VE.find_uv()


def test_find_uv_prefers_its_own_uv_to_the_path():
"""
With MU_UV unset, Nu's own uv (the `uv` package's binary, a version it
needs) wins over a `uv` on the PATH, which may be older.
"""
bundled = "/opt/mu/app_packages/uv/bin/uv"
with mock.patch.dict(os.environ, {}, clear=True):
with (
mock.patch.object(VE.shutil, "which", return_value="/usr/bin/uv") as which,
mock.patch.object(VE, "_uv_from_package", return_value=bundled),
):
assert VE.find_uv() == bundled
which.assert_not_called()


def test_find_uv_falls_back_to_path():
"""With MU_UV unset, fall back to `uv` on the PATH."""
"""With MU_UV unset and no uv package, use `uv` on the PATH."""
found = "/usr/local/bin/uv"
with mock.patch.dict(os.environ, {}, clear=True):
with mock.patch.object(VE.shutil, "which", return_value=found) as which:
with (
mock.patch.object(VE.shutil, "which", return_value=found) as which,
mock.patch.object(VE, "_uv_from_package", return_value=None),
):
assert VE.find_uv() == found
which.assert_called_once_with("uv")


def test_find_uv_falls_back_to_bundled_package():
"""With MU_UV unset and nothing on PATH, use the binary bundled by the
`uv` PyPI package (the packaged-app path)."""
bundled = "/opt/mu/app_packages/uv/bin/uv"
with mock.patch.dict(os.environ, {}, clear=True):
with mock.patch.object(VE.shutil, "which", return_value=None):
with mock.patch.object(VE, "_uv_from_package", return_value=bundled):
assert VE.find_uv() == bundled


def test_find_uv_not_found():
"""No MU_UV, nothing on PATH, and no bundled uv raises UvNotFound."""
with mock.patch.dict(os.environ, {}, clear=True):
Expand Down
16 changes: 12 additions & 4 deletions tests/virtual_environment/test_virtual_environment.py
Original file line number Diff line number Diff line change
Expand Up @@ -921,11 +921,19 @@ def test_find_uv_from_environment_missing(monkeypatch, tmp_path):


def test_find_uv_from_path(monkeypatch):
"""With no MU_UV override, fall back to `uv` on the PATH."""
"""
With no MU_UV override and no `uv` package of Nu's own, fall back to
`uv` on the PATH.
"""
monkeypatch.delenv(mu.virtual_environment.UV_ENV_VAR, raising=False)
with mock.patch.object(
mu.virtual_environment.shutil, "which", return_value="/usr/bin/uv"
) as which:
with (
mock.patch.object(
mu.virtual_environment.shutil, "which", return_value="/usr/bin/uv"
) as which,
mock.patch.object(
mu.virtual_environment, "_uv_from_package", return_value=None
),
):
assert mu.virtual_environment.find_uv() == "/usr/bin/uv"
which.assert_called_once_with("uv")

Expand Down
Loading