Cut the version helper down to what the callers need

No caller passes an sdist tar - android extracts it and passes the tree -
so drop the tarfile reader, and drop argparse for a positional read. That
leaves one function over a tree or a wheel, halving the helper and its
test. Trim the surrounding comments and the Android error path to match.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: rtibblesbot

Makefile

@@ -201,9 +201,8 @@ set-no-uv-python-version-for-tests:
 	echo "__version__ = version = \"$$VERSION\"" >> kolibri/_version.py; \
 	echo "Set version to $$VERSION"
 
-# kolibri/VERSION is a plaintext copy for external consumers only; in-repo, use
-# build_tools/read_kolibri_version.py. Don't drop it: kolibri-installer-debian
-# (Makefile:18-21 at v0.16.1) reads it from our sdist, reddening the `deb` job.
+# Plaintext copy read out of our sdist by kolibri-installer-debian (pinned
+# v0.16.1) — deleting it reddens `deb`. In-repo, use read_kolibri_version.py.
 writeversion:
 	uv run python -c "import kolibri; print(kolibri.__version__)" > kolibri/VERSION
 	@echo ""

build_tools/read_kolibri_version.py

@@ -3,90 +3,38 @@
 # dependencies = []
 # ///
 """
-Print the Kolibri version out of a directory tree, a wheel, or an sdist.
+Print the Kolibri version from ``kolibri/_version.py``, the setuptools-scm output
+that is Kolibri's source of truth, given either a directory holding the
+``kolibri`` package or a built ``.whl`` -- whichever the caller has to hand.
 
-``kolibri/_version.py`` -- written by setuptools-scm -- is the source of truth.
-Each platform under platforms/ holds a different entity at its version-read
-point, hence the three. Per-platform version *conversions* (PEP 440 to Debian,
-Android versionCode) stay with the platform that needs them.
-
-Stdlib-only and Python 3.6-compatible: callers may run it under a bare
-``python3`` with no workspace venv, and its tests run on 3.6 and 3.7 in
-tox.yml's ``unit_test_no_uv`` job.
+Stdlib-only and 3.6-compatible: callers run it under a bare ``python3`` with no
+workspace venv.
 """
 
-import argparse
 import ast
 import os
-import tarfile
+import sys
 import zipfile
 
 VERSION_MODULE = "kolibri/_version.py"
 
 
-def _parse_version(source):
-    """Return the ``__version__`` assigned in the text of a ``_version.py``."""
+def read_version(path):
+    if path.endswith(".whl"):
+        with zipfile.ZipFile(path) as wheel:
+            source = wheel.read(VERSION_MODULE).decode("utf-8")
+    else:
+        with open(os.path.join(path, VERSION_MODULE)) as version_module:
+            source = version_module.read()
+    # ast, not exec: handles either quoting style without running build output.
     for node in ast.parse(source).body:
         if isinstance(node, ast.Assign) and any(
             isinstance(target, ast.Name) and target.id == "__version__"
             for target in node.targets
         ):
             return ast.literal_eval(node.value)
-    raise ValueError("No __version__ assignment found in {}".format(VERSION_MODULE))
-
-
-def _read_tree(path):
-    version_module = os.path.join(path, VERSION_MODULE)
-    if not os.path.isfile(version_module):
-        raise ValueError("No {} in tree: {}".format(VERSION_MODULE, path))
-    with open(version_module) as f:
-        return f.read()
-
-
-def _read_wheel(path):
-    # A wheel holds the package at the archive root, alongside its .dist-info.
-    with zipfile.ZipFile(path) as archive:
-        try:
-            return archive.read(VERSION_MODULE).decode("utf-8")
-        except KeyError:
-            raise ValueError("No {} in wheel: {}".format(VERSION_MODULE, path))
-
-
-def _read_sdist(path):
-    # An sdist nests everything under a single root component.
-    with tarfile.open(path) as archive:
-        for member in archive:
-            if member.name.partition("/")[2] == VERSION_MODULE:
-                with archive.extractfile(member) as version_module:
-                    return version_module.read().decode("utf-8")
-    raise ValueError("No {} in sdist: {}".format(VERSION_MODULE, path))
-
-
-def read_version(path):
-    """Return the Kolibri version held by a tree, a wheel, or an sdist."""
-    if os.path.isdir(path):
-        return _parse_version(_read_tree(path))
-    # A missing path is the likeliest failure, and "not a .whl" would mislead.
-    if not os.path.isfile(path):
-        raise ValueError("No such tree, wheel or sdist: {}".format(path))
-    if path.endswith(".whl"):
-        return _parse_version(_read_wheel(path))
-    if path.endswith(".tar.gz"):
-        return _parse_version(_read_sdist(path))
-    raise ValueError("Not a .whl or a .tar.gz sdist: {}".format(path))
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description=__doc__,
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-    )
-    parser.add_argument(
-        "path",
-        help="a directory tree containing kolibri/, a .whl, or a .tar.gz sdist",
-    )
-    print(read_version(parser.parse_args().path))  # noqa: T201
+    raise ValueError("No __version__ assignment in {}: {}".format(path, VERSION_MODULE))
 
 
 if __name__ == "__main__":
-    main()
+    print(read_version(sys.argv[1]))  # noqa: T201

platforms/android/README.md

@@ -20,10 +20,8 @@ root above it, so history and `git blame` still work.
 The build consumes the shared workspace rather than a standalone checkout:
 
 - **Python / `buildPython`:** resolves to the shared root `.venv`. Create it with
-  `uv sync --group dev --all-packages` — uv finds the workspace root from any
-  member directory, so this works from `platforms/android/` too. The venv lands
-  at the monorepo root; nothing needs activating, since both the Makefile and
-  `app/build.gradle` resolve `../../../.venv` directly.
+  `uv sync --group dev --all-packages` from anywhere in the workspace. Nothing
+  needs activating — the Makefile and `app/build.gradle` resolve it directly.
 - **Chaquopy runtime:** the embedded runtime (`requirements.txt`) stays
   Chaquopy-resolved and out of the workspace lock — install it into the shared
   `.venv` with `uv pip install -r requirements.txt`.

platforms/android/app/build.gradle

@@ -104,16 +104,9 @@ def calculatedVersionName
 def calculatedVersionCode
 
 if (extractedKolibriDir.exists() && extractedKolibriDir.isDirectory()) {
-	// setuptools-scm's _version.py is the version source of truth; read it via
-	// the shared monorepo helper.
-	def kolibriVersionFile = new File(extractedKolibriDir, 'kolibri/_version.py')
-	if (!kolibriVersionFile.exists()) {
-		throw new GradleException(
-				"Kolibri _version.py not found at: ${kolibriVersionFile}\n" +
-				"Kolibri tars released before the monorepo do not contain it - " +
-				"stage a workspace-built tar with 'make stage-workspace-tar'.")
-	}
-
+	// Read the version with the shared monorepo helper, as versionCode below
+	// shells out to scripts/version.py. Pre-monorepo tars have no _version.py,
+	// so the helper fails here: stage one with 'make stage-workspace-tar'.
 	def versionOutput = new ByteArrayOutputStream()
 	exec {
 		commandLine buildPythonExecutable,

platforms/desktop-app/Makefile

@@ -18,15 +18,10 @@ guard-%:
 	fi
 
 # kolibrisrc/ is what PyInstaller ships, so its kolibri/_version.py is the app
-# version. $(shell) discards the helper's exit status, so guard on empty output —
-# otherwise a failed read leaves the version blank and the build carries on.
+# version. $(shell) hides a failed read as an empty one, hence the guard.
 needs-version:
 	$(eval KOLIBRI_VERSION ?= $(shell $(PYTHON_EXEC) ../../build_tools/read_kolibri_version.py kolibrisrc))
-	@if [ -z "$(KOLIBRI_VERSION)" ]; then \
-		echo "Could not read the Kolibri version from kolibrisrc/ (see the error above)."; \
-		echo "Stage a workspace-built whl with 'make stage-workspace-whl'."; \
-		exit 1; \
-	fi
+	@test -n "$(KOLIBRI_VERSION)" || { echo "No Kolibri version in kolibrisrc/: stage a whl with 'make stage-workspace-whl'"; exit 1; }
 
 # Write the app version (= the bundled Kolibri version) to _version.py so
 # PyInstaller bundles it and kolibri_app.__init__ can

platforms/desktop-app/README.md

@@ -68,11 +68,11 @@ Builds Kolibri from the monorepo workspace and stages it into `whl/`, so the app
   ```
 
 - **Or Fetch and Prepare a Published Kolibri Wheel:**
-You'll need the URL of the Kolibri `.whl` you intend to package — see the [Kolibri GitHub Releases page](https://github.com/learningequality/kolibri/releases). The build reads the app version from `kolibri/_version.py`, which no wheel published so far contains, so this path needs a wheel built after Kolibri adopted setuptools-scm; otherwise use `stage-workspace-whl`.
+Takes the URL of a `.whl` from the [Kolibri GitHub Releases page](https://github.com/learningequality/kolibri/releases). The version read needs `kolibri/_version.py`, which no released wheel ships yet.
   ```
   make get-whl whl="<URL_TO_KOLIBRI_WHL_FILE>"
   ```
-  **Example** (a v0.18.0 wheel predates `_version.py`, so it fails the version read):
+  **Example:**
   ```
   make get-whl whl="https://github.com/learningequality/kolibri/releases/download/v0.18.0/kolibri-0.18.0-py2.py3-none-any.whl"
   ```

test/test_read_kolibri_version.py

@@ -1,30 +1,11 @@
 """Unit tests for build_tools/read_kolibri_version.py."""
 
-Each caller holds a different entity at its version-read point: an extracted
-sdist tree (android), an unpacked wheel tree (desktop-app), the repo checkout
-(debian-server CI), a built wheel (the root `pex` target). These pin the
-archive-layout differences the helper absorbs.
-
-Stdlib-only and 3.6-compatible: tox.yml's `unit_test_no_uv` job runs this
-directory under a bare `python` in python:3.6-buster and python:3.7-buster.
-"""
-
-import importlib.util
-import io
 import os
-import tarfile
 import zipfile
 
 import pytest
 
-_MODULE_PATH = os.path.join(
-    os.path.dirname(os.path.dirname(os.path.realpath(__file__))),
-    "build_tools",
-    "read_kolibri_version.py",
-)
-_spec = importlib.util.spec_from_file_location("read_kolibri_version", _MODULE_PATH)
-read_kolibri_version = importlib.util.module_from_spec(_spec)
-_spec.loader.exec_module(read_kolibri_version)
+from build_tools.read_kolibri_version import read_version
 
 VERSION = "0.19.0.dev0+g1234abc"
 
@@ -56,70 +37,14 @@ def test_reads_the_double_quoted_form(tmp_path):
 
 
 def test_reads_version_from_a_wheel(tmp_path):
+    # A wheel holds the package at the archive root, unlike an extracted tree.
     whl = os.path.join(str(tmp_path), "kolibri-0.19.0-py2.py3-none-any.whl")
     with zipfile.ZipFile(whl, "w") as archive:
         archive.writestr("kolibri/_version.py", SCM_VERSION_PY)
         archive.writestr("kolibri-0.19.0.dist-info/METADATA", "Name: kolibri\n")
     assert read_version(whl) == VERSION
 
 
-def test_reads_version_from_an_sdist(tmp_path):
-    # The root component is the one android strips with --strip-components=1.
-    sdist = os.path.join(str(tmp_path), "kolibri-0.19.0.tar.gz")
-    payload = SCM_VERSION_PY.encode("utf-8")
-    member = tarfile.TarInfo("kolibri-0.19.0/kolibri/_version.py")
-    member.size = len(payload)
-    with tarfile.open(sdist, "w:gz") as archive:
-        archive.addfile(member, io.BytesIO(payload))
-    assert read_kolibri_version.read_version(sdist) == VERSION
-
-
-def test_wheel_without_a_version_file_raises(tmp_path):
-    whl = os.path.join(str(tmp_path), "kolibri-0.19.0-py2.py3-none-any.whl")
-    with zipfile.ZipFile(whl, "w") as archive:
-        archive.writestr("kolibri-0.19.0.dist-info/METADATA", "Name: kolibri\n")
-    with pytest.raises(ValueError) as excinfo:
-        read_kolibri_version.read_version(whl)
-    assert whl in str(excinfo.value)
-
-
-def test_sdist_without_a_version_file_raises(tmp_path):
-    sdist = os.path.join(str(tmp_path), "kolibri-0.19.0.tar.gz")
-    member = tarfile.TarInfo("kolibri-0.19.0/kolibri/__init__.py")
-    member.size = 0
-    with tarfile.open(sdist, "w:gz") as archive:
-        archive.addfile(member, io.BytesIO(b""))
-    with pytest.raises(ValueError) as excinfo:
-        read_kolibri_version.read_version(sdist)
-    assert sdist in str(excinfo.value)
-
-
-def test_tree_without_a_version_file_raises(tmp_path):
-    with pytest.raises(ValueError) as excinfo:
-        read_kolibri_version.read_version(str(tmp_path))
-    assert str(tmp_path) in str(excinfo.value)
-
-
-def test_unrecognized_suffix_raises(tmp_path):
-    # raspberry-pi reads a .deb filename instead, deliberately. Anyone pointing
-    # this helper at one should get an error, not a silent misparse.
-    deb = os.path.join(str(tmp_path), "kolibri_0.19.0-0ubuntu1_all.deb")
-    with open(deb, "wb") as f:
-        f.write(b"")
-    with pytest.raises(ValueError) as excinfo:
-        read_kolibri_version.read_version(deb)
-    assert deb in str(excinfo.value)
-
-
-def test_missing_entity_raises(tmp_path):
-    # The likeliest failure in every caller: nothing has been staged yet, so
-    # kolibrisrc/ or tar/extracted/ simply is not there.
-    missing = os.path.join(str(tmp_path), "kolibrisrc")
-    with pytest.raises(ValueError) as excinfo:
-        read_kolibri_version.read_version(missing)
-    assert missing in str(excinfo.value)
-
-
 def test_version_alias_alone_raises(tmp_path):
     with pytest.raises(ValueError):
         read_version(_write_tree(tmp_path, "version = '%s'\n" % VERSION))