From d2ab9a00bec7b2cf744b9236c2949428681daeaf Mon Sep 17 00:00:00 2001 From: chrg6 Date: Thu, 12 Nov 2026 07:16:14 -0500 Subject: [PATCH] Check at startup that the launcher's Python can read zstd files, and say how to fix it when it cannot. Run from a checkout, the launcher uses the Python that started it. A Python older than 3.14 without the zstandard package got through the first-run screen and stopped at Gather Build Tools with only "No module named 'zstandard'", after the packages were downloaded. toolchain.zstd_missing now looks for compression.zstd or zstandard when the launcher starts. Without either, the log and the first screen name the Python and give the pip line for tools/requirements-launcher.txt, and Gather Build Tools stops with the same message before it unpacks anything. A release's own Python always has the package; if it ever lacks it, the message says to reinstall NX2navi. Co-Authored-By: Claude Opus 5.5 --- docs/launcher.md | 6 ++++++ launcher/context.py | 4 ++++ launcher/jobs.py | 3 +++ launcher/toolchain.py | 20 ++++++++++++++++++++ launcher/ui/app.py | 2 ++ tests/launcher_test.py | 13 +++++++++++++ 6 files changed, 48 insertions(+) diff --git a/docs/launcher.md b/docs/launcher.md index b05fdb6f..8d16028a 100644 --- a/docs/launcher.md +++ b/docs/launcher.md @@ -99,6 +99,12 @@ for updates); an XInput gamepad (d-pad or left stick, A, B, Y) while the window `python -m launcher --selftest --shots DIR` draws every screen with made-up states and saves a PNG of each. +Run from a checkout, the launcher and the build use the Python that started it, which needs the packages of +`tools/requirements-launcher.txt`. At startup the launcher checks that this Python can read zstd files +(`toolchain.zstd_missing`: Python 3.14's `compression.zstd`, or the `zstandard` package). If it cannot, the first screen +and the log say so and give the `pip install` line, and Gather Build Tools stops with the same message before it +unpacks anything. + ## The launcher's folder ``` diff --git a/launcher/context.py b/launcher/context.py index b7fd1eae..0710a864 100644 --- a/launcher/context.py +++ b/launcher/context.py @@ -29,6 +29,10 @@ class Context: self._file = None self.log(f'--- NX2navi launcher {self.version} ({"checkout" if self.layout.dev else "release"}) in ' f'{self.layout.root}') + from .toolchain import zstd_missing + self.zstd_missing = zstd_missing(self.layout) + if self.zstd_missing: + self.log(self.zstd_missing) if self.settings.unreadable: self.log(f'{self.layout.settings} is not valid JSON: the settings start from their defaults; the file as ' 'it was is kept as launcher.json.bad') diff --git a/launcher/jobs.py b/launcher/jobs.py index a411236f..5617fb38 100644 --- a/launcher/jobs.py +++ b/launcher/jobs.py @@ -276,6 +276,9 @@ class Job: def ensure_tools(self, sid): layout = self.ctx.layout self.begin(sid) + missing = toolchain.zstd_missing(layout) + if missing: + raise toolchain.ToolchainError(missing) lock = toolchain.load_lock(layout, self.ctx.version) if toolchain.is_current(layout, lock): have_tools = True diff --git a/launcher/toolchain.py b/launcher/toolchain.py index cf88fc87..846d333f 100644 --- a/launcher/toolchain.py +++ b/launcher/toolchain.py @@ -16,6 +16,7 @@ zbic (GPL-2.0) unpacks the game's compressed program files. The release does not wheel for its own Python from PyPI and unpacks it into pydeps/, as `pip install zbic` would. """ import hashlib +import importlib import io import json import os @@ -53,6 +54,25 @@ class ToolchainError(Exception): # ---------------------------------------------------------------- the package database +def zstd_missing(layout): + """Why this Python cannot read zstd files, or '' when it can. The MSYS2 packages and the game's files are zstd: + Python 3.14 reads them with compression.zstd, an older Python needs the zstandard package. The release's Python + has both; a checkout runs under whatever Python started it, and without either the build stopped at its first + unpack with nothing but "No module named 'zstandard'".""" + for name in ('compression.zstd', 'zstandard'): + try: + importlib.import_module(name) + return '' + except ImportError: + pass + ver = '.'.join(map(str, sys.version_info[:3])) + if not layout.dev: + return f'The launcher\'s Python ({ver}) is missing its zstandard package. Reinstall NX2navi.' + req = layout.app / 'tools' / 'requirements-launcher.txt' + return (f'This Python ({ver}) cannot unpack the build tools: before 3.14 it needs the zstandard package. ' + f'Install the launcher\'s packages with: "{sys.executable}" -m pip install -r "{req}"') + + def _zstd_decompress_stream(data): try: from compression import zstd # Python 3.14 diff --git a/launcher/ui/app.py b/launcher/ui/app.py index 3691d541..28695537 100644 --- a/launcher/ui/app.py +++ b/launcher/ui/app.py @@ -744,6 +744,8 @@ class App: self.ctx.log(f'the stub went back from {a.rolled_back} to {self.layout.version}') self.settings['rolled_back'] = versions.display(a.rolled_back) # never installed again by itself self.settings.save() + if self.ctx.zstd_missing: # told at once, not when Begin Installation stops at the build tools + self.message = self.ctx.zstd_missing for old in self.layout.root.glob('python.old*'): # the Python an update replaced (launcher/native/nx2navi.c) shutil.rmtree(old, ignore_errors=True) if gd or self.settings.get('dump'): diff --git a/tests/launcher_test.py b/tests/launcher_test.py index c3b54d30..8cb0a1c0 100644 --- a/tests/launcher_test.py +++ b/tests/launcher_test.py @@ -498,6 +498,19 @@ class UninstallTest(Tmp): # ---------------------------------------------------------------- toolchain class ToolchainTest(Tmp): + def test_zstd_missing(self): + """A Python without compression.zstd and zstandard is named at startup, with the pip line for a checkout.""" + with mock.patch.dict(sys.modules, {'compression.zstd': None, 'zstandard': mock.MagicMock()}): + self.assertEqual(toolchain.zstd_missing(self.layout), '') + with mock.patch.dict(sys.modules, {'compression.zstd': None, 'zstandard': None}): + msg = toolchain.zstd_missing(self.layout) + ctx = Context(self.layout) + self.assertIn('zstandard', msg) + self.assertIn('-m pip install -r', msg) + self.assertIn('requirements-launcher.txt', msg) + self.assertEqual(ctx.zstd_missing, msg) + self.assertTrue(any(msg in line for line in ctx.log_tail())) + def test_resolve_and_install(self): repo = self.tmp / 'repo' repo.mkdir()