From 15b06163b07bac78fa49aaeacb69346f49a3a6df Mon Sep 17 00:00:00 2001 From: Evan Gress <106449014+evangress@users.noreply.github.com> Date: Sat, 14 Nov 2026 11:45:20 -0500 Subject: [PATCH] Prefer Nu's own uv to one on the PATH find_uv() checked the PATH before the uv wheel Nu depends on, so an installed Nu used whatever uv a learner had installed (the Windows MSI check found it using one from a Python's Scripts folder). Nu needs uv>=0.9.8 (`uv pip install --excludes` for plugins), and an older uv on the PATH would break adding plugins. Now: MU_UV -> the uv package's binary -> the PATH, only if Nu has none of its own. Co-Authored-By: Claude Opus 5.5 --- CHANGES.md | 4 ++- CLAUDE.md | 2 +- docs/environment.md | 5 ++- docs/packaging.md | 4 ++- mu/virtual_environment.py | 24 ++++++++------ tests/virtual_environment/test_uv.py | 32 ++++++++++++------- .../test_virtual_environment.py | 16 +++++++--- 7 files changed, 57 insertions(+), 30 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 090b879c8..0e474f699 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md index f01bb1a32..21846cb54 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 --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: · 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 --script ` 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 --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: · 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 --script ` 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. diff --git a/docs/environment.md b/docs/environment.md index b0203872d..ddba0a291 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -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. diff --git a/docs/packaging.md b/docs/packaging.md index 93f0d6dc8..ee9f8efc7 100644 --- a/docs/packaging.md +++ b/docs/packaging.md @@ -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)). diff --git a/mu/virtual_environment.py b/mu/virtual_environment.py index 4061badaf..6a46f0326 100644 --- a/mu/virtual_environment.py +++ b/mu/virtual_environment.py @@ -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 @@ -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) @@ -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 diff --git a/tests/virtual_environment/test_uv.py b/tests/virtual_environment/test_uv.py index 769d1dd36..def3e255f 100644 --- a/tests/virtual_environment/test_uv.py +++ b/tests/virtual_environment/test_uv.py @@ -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): diff --git a/tests/virtual_environment/test_virtual_environment.py b/tests/virtual_environment/test_virtual_environment.py index 1071eb124..3646a5b24 100644 --- a/tests/virtual_environment/test_virtual_environment.py +++ b/tests/virtual_environment/test_virtual_environment.py @@ -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")