From dd84ccf2ffa73f218f48710f3c8460f6831a3932 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Hidalgo?= <47150974+IvanHCenalmor@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:09:28 +0200 Subject: [PATCH] Template 0.1.32: the user docs link to the guide that owns a topic tools_bridge.md no longer repeats the plugins' install situation, the Tools authoring guide (form markers, outputs, check/test) or the Tools pin's version. It keeps what the template owns (where an app declares its tools, what the installer does, where the pin is set and how it is moved) and links to the owner guides: the Site's image-software, napari, Fiji and QuPath guides, and LabConstrictor-Tools docs/AUTHORING.md (on GitHub for now). install.md links to the image-software guide; napari in lower case. Migration 0.1.31 -> 0.1.32 delivers it: tools_bridge.md is replaced only when it is the 0.1.31 template file, install.md and the docs README get exact-text edits, customised files are SKIPPED, line endings are kept. Design note migration_0_1_32.md, tests, and before_0_1_32 chained into the older test helpers. Co-Authored-By: Claude Opus 5.5 --- .template_sync/manifest.yaml | 5 +- .../migrations/v0_1_31_to_v0_1_32.py | 132 +++++++++++ .../.tools/docs/tools_bridge.md | 81 +++++++ .../previous/.tools/docs/tools_bridge.md | 59 +++++ .tools/docs/README.md | 2 +- .tools/docs/install.md | 4 +- .tools/docs/migration_0_1_32.md | 44 ++++ .tools/docs/tools_bridge.md | 108 +++++---- tests/_v0_1_31.py | 5 +- tests/_v0_1_32.py | 44 ++++ tests/test_template_sync_0_1_17.py | 4 +- tests/test_template_sync_0_1_28.py | 15 +- tests/test_template_sync_0_1_30.py | 12 +- tests/test_template_sync_0_1_32.py | 216 ++++++++++++++++++ 14 files changed, 676 insertions(+), 55 deletions(-) create mode 100644 .template_sync/migrations/v0_1_31_to_v0_1_32.py create mode 100644 .template_sync/resources/v0_1_31_to_v0_1_32/.tools/docs/tools_bridge.md create mode 100644 .template_sync/resources/v0_1_31_to_v0_1_32/previous/.tools/docs/tools_bridge.md create mode 100644 .tools/docs/migration_0_1_32.md create mode 100644 tests/_v0_1_32.py create mode 100644 tests/test_template_sync_0_1_32.py diff --git a/.template_sync/manifest.yaml b/.template_sync/manifest.yaml index 171f0c7..7de3f90 100644 --- a/.template_sync/manifest.yaml +++ b/.template_sync/manifest.yaml @@ -1,4 +1,4 @@ -template_version: 0.1.31 +template_version: 0.1.32 migrations: - from: 0.0.0 to: 0.0.1 @@ -99,3 +99,6 @@ migrations: - from: 0.1.30 to: 0.1.31 script: migrations/v0_1_30_to_v0_1_31.py + - from: 0.1.31 + to: 0.1.32 + script: migrations/v0_1_31_to_v0_1_32.py diff --git a/.template_sync/migrations/v0_1_31_to_v0_1_32.py b/.template_sync/migrations/v0_1_31_to_v0_1_32.py new file mode 100644 index 0000000..7b1d817 --- /dev/null +++ b/.template_sync/migrations/v0_1_31_to_v0_1_32.py @@ -0,0 +1,132 @@ +"""Template 0.1.31 -> 0.1.32: the user docs link to the guide that owns a topic instead of repeating it. + +Design note: https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_32.md + +Each topic of the LabConstrictor documentation is written on one page, and every other page links to it. The plugins' install steps belong +to the plugin guides on the website, and how to write tools belongs to LabConstrictor-Tools. The template keeps what is its own: where an +app declares its tools and what the installer does with them. + +What this changes in an app repository (every step is independent, idempotent and never deletes anything): + +1. .tools/docs/tools_bridge.md is replaced by the 0.1.32 guide when it is still the 0.1.31 template file. The guide no longer repeats the + plugins' install steps, the list of form markers and the test commands of LabConstrictor-Tools, or the version of the Tools pin; it links + to the owner guides instead. A file the app changed itself stays as it is (SKIPPED). +2. .tools/docs/install.md: "Where the app is listed" writes napari in lower case and links to the guide that says how to run the tools. +3. .tools/docs/README.md: the entry of the tools guide writes napari in lower case. + +Steps 2 and 3 replace one exact piece of template text each and leave a file alone when that text is not there (SKIPPED). The line endings +of each file are kept. The changes reach users with the app's next release. +""" +from __future__ import annotations + +from pathlib import Path +from typing import Any + + +DOCS_URL = "https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_32.md" +TAG = "[migration 0.1.32]" +RESOURCE_ROOT = Path(__file__).resolve().parents[1] / "resources" / "v0_1_31_to_v0_1_32" +PREVIOUS_ROOT = RESOURCE_ROOT / "previous" + +TOOLS_DOC = Path(".tools/docs/tools_bridge.md") +INSTALL_DOC = Path(".tools/docs/install.md") +DOCS_INDEX = Path(".tools/docs/README.md") + +SITE = "https://cellmigrationlab.github.io/LabConstrictor-Site/" + +# Files replaced whole, only when they are the 0.1.31 template file (compared with LF line endings). +WHOLE_FILES = (TOOLS_DOC,) + +# (old, new) pairs, written with LF line endings; a file with CRLF line endings gets them with CRLF. +EDITS: dict[Path, tuple[tuple[str, str], ...]] = { + INSTALL_DOC: ( + ("If the app ships tools for Napari, Fiji or QuPath, the installer registers them with LabConstrictor Tools", + "If the app ships tools for napari, Fiji or QuPath, the installer registers them with LabConstrictor Tools"), + ("with `hosts: [notebook, napari]` the app is listed in Napari, and not in Fiji or QuPath.", + "with `hosts: [notebook, napari]` the app is listed in napari, and not in Fiji or QuPath."), + ("so it is listed in every host; ...`).\n", + "so it is listed in every host; ...`).\n" + "\n" + "To run the tools, install the plugin for your image software once: see" + f" [Use apps inside napari, Fiji and QuPath]({SITE}guides/image-software/).\n"), + ), + DOCS_INDEX: ( + ("- [Expose tools to Napari, Fiji and QuPath (experimental)](tools_bridge.md)\n", + "- [Expose tools to napari, Fiji and QuPath (experimental)](tools_bridge.md)\n"), + ), +} +FILES = (*WHOLE_FILES, *EDITS) + + +def log(message: str) -> None: + print(f"{TAG} {message}") + + +def apply_edits(text_lf: str, edits: tuple[tuple[str, str], ...]) -> tuple[str, int, int]: + """`text_lf` with each pair applied whose old text occurs exactly once and whose new text is not there yet. Returns the text, the + pairs applied and the pairs not found (neither the old text once nor the new text present).""" + applied = missing = 0 + for old, new in edits: + if new in text_lf: + continue + if text_lf.count(old) == 1: + text_lf = text_lf.replace(old, new) + applied += 1 + else: + missing += 1 + return text_lf, applied, missing + + +def replaced_file(relative: Path, text_lf: str) -> tuple[str, str]: + """The 0.1.32 text of a whole-file step, and what was done. The text is unchanged when the file is not the 0.1.31 template file.""" + new = (RESOURCE_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n") + if text_lf == new: + return text_lf, "already up to date" + previous = (PREVIOUS_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n") + if text_lf != previous: + return text_lf, f"SKIPPED: customised (not the 0.1.31 template file), so it was left unchanged; compare it with the template's file. See {DOCS_URL}" + return new, "replaced by the 0.1.32 guide" + + +def edited_file(relative: Path, text_lf: str) -> tuple[str, str]: + """The text after the exact-text edits of `relative`, and what was done.""" + edits = EDITS[relative] + text, applied, missing = apply_edits(text_lf, edits) + if not missing: + return text, f"{applied} text change(s)" if applied else "already up to date" + if missing == len(edits): + return text, f"SKIPPED: customised (the 0.1.31 text was not found), so it was left unchanged. See {DOCS_URL}" + skipped = f"SKIPPED {missing} passage(s) that differ from the template text (left as they are). See {DOCS_URL}" + return text, f"{applied} text change(s); {skipped}" if applied else f"the other changes are there; {skipped}" + + +def update(path: Path, relative: Path) -> str: + data = path.read_bytes().decode("utf-8") + newline = "\r\n" if "\r\n" in data else "\n" + original = data.replace("\r\n", "\n") + text, note = replaced_file(relative, original) if relative in WHOLE_FILES else edited_file(relative, original) + if text == original: + return note if note.startswith("SKIPPED") else f"unchanged: {note}" + path.write_bytes(text.replace("\n", newline).encode("utf-8")) + return f"updated: {note}" + + +def migrate(repo_root: Path, context: dict[str, Any]) -> None: + """Apply the 0.1.32 documentation changes (idempotent, surgical, never raises for a customised file).""" + _ = context + changed = 0 + for relative in FILES: + path = repo_root / relative + if not path.is_file(): + log(f"{relative}: not present in this repository (nothing was created)") + continue + try: + status = update(path, relative) + except (OSError, UnicodeDecodeError) as exc: + status = f"SKIPPED: {exc}; left unchanged. See {DOCS_URL}" + changed += status.startswith("updated") + log(f"{relative}: {status}") + if changed: + log(f"done: {changed} file(s) changed. The changes reach users with the next release of the app.") + else: + log("done: no repository changes were required.") diff --git a/.template_sync/resources/v0_1_31_to_v0_1_32/.tools/docs/tools_bridge.md b/.template_sync/resources/v0_1_31_to_v0_1_32/.tools/docs/tools_bridge.md new file mode 100644 index 0000000..9599e53 --- /dev/null +++ b/.template_sync/resources/v0_1_31_to_v0_1_32/.tools/docs/tools_bridge.md @@ -0,0 +1,81 @@ +# Expose your app's tools to napari, Fiji and QuPath (optional, experimental) + +If your repository ships Python code (see [Upload external code](external_code_upload.md)), you can declare some of its functions +as **tools**. After installation, people can run them in napari, Fiji and QuPath and from the command line, with forms made from the +function signatures. Nothing changes for apps that do not declare tools. + +This page covers what the template does: where you declare the tools and what the installer does with them. Two other guides cover the rest: + +- [Writing tools](https://github.com/CellMigrationLab/LabConstrictor-Tools/blob/main/docs/AUTHORING.md), in LabConstrictor-Tools: the inputs + and outputs a tool can have, how to lay out its form, what each program supports, and how to test a tool. +- [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/): what the people + who install your app do to run its tools, with the install steps of the + [napari plugin](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/napari/), the + [Fiji plugin](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/fiji/) and the + [QuPath extension](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/qupath/). + +## Declare your tools + +1. Add a module named `_lc_tools` next to your package under `src/` (so `src/mytool_lc_tools/__init__.py` for + the package `mytool`). The installer registers tools only from a module with exactly this name. Declare tools in it with typed + functions, and import your science code **inside** the functions: + + ```python + from typing import Annotated + from labconstrictor_tools import Image, ImageOut, Min, tool + + @tool("Gaussian blur") + def blur(image: Image, sigma: Annotated[float, Min(0)] = 2.0) -> ImageOut: + from mytool.filters import gaussian + return gaussian(image, sigma) + ``` + + Keep the module light: it is imported to read the tool list, so heavy imports at the top slow every start. +2. Import `labconstrictor_tools` only in `_lc_tools`, or inside functions, if you can. The rest of your package then also works + where LabConstrictor Tools is not installed: a notebook run on Google Colab, a copy of the package used elsewhere, or an installation where + Tools failed to install. An import at the top of your package does not stop the installation, because the installer installs Tools before + it checks that your package can be imported. +3. Name the programs your tools work in under `hosts:` in `labconstrictor-app.yaml`: see [Describe your app for the App Centre](app_manifest.md). +4. Test your tools before you publish a release, as [Writing tools](https://github.com/CellMigrationLab/LabConstrictor-Tools/blob/main/docs/AUTHORING.md) + shows (`labconstrictor-tools check` and `labconstrictor-tools test`). + +## What the installer does + +The installer's `post_install` step: + +1. installs your package; +2. if your package has a `_lc_tools` module, installs LabConstrictor Tools; +3. checks that your package can be imported; +4. registers the app (`labconstrictor-tools register ...`) with the version from the `version:` line of `construct.yaml` and the hosts of + `labconstrictor-app.yaml`. + +When the app is uninstalled, `pre_uninstall` unregisters it. + +A failure in step 2 or 4 is written as a `WARNING` to `menuinst_debug.log` in the install folder, the registration is skipped, and the +installation goes on. The one exception is a package that needs Tools to be imported: then the import check of step 3 fails, as it should. + +The Windows step (`post_install.bat`) runs in the template's automated tests on a Windows machine, and people have installed apps on Windows +and macOS from a clean system. + +### Which LabConstrictor Tools the installer installs + +LabConstrictor Tools is not on PyPI yet. The installer downloads the GitHub archive of one release tag of LabConstrictor-Tools, a plain zip +file, so the user's computer does not need git. The tag is pinned: two installers built from the same app release install the same Tools, +and a change to Tools does not reach new installations until the pin is moved on purpose. Template updates move the pin in your app. + +The tag is the value of `LC_TOOLS_PIN` in both scripts: +[app/bash_bat_scripts/post_install.sh](../../app/bash_bat_scripts/post_install.sh) (`LC_TOOLS_PIN="..."`) and +[app/bash_bat_scripts/post_install.bat](../../app/bash_bat_scripts/post_install.bat) (`SET "LC_TOOLS_PIN=..."`). + +To install Tools from somewhere else, set the environment variable `LC_TOOLS_SPEC` when the installer runs: a wheel, a git URL, a mirror, or +the name `labconstrictor-tools` once it is on PyPI. It replaces the pin completely. + +**Move the pin (template maintainers).** Create and test the tag in LabConstrictor-Tools (the procedure is in its `docs/OPERATIONS.md`). +Change `LC_TOOLS_PIN` in both scripts of the template, and in the copies under `.template_sync/resources/` of the latest migration if it has +them (the test `test_resources_are_identical_to_the_template_files` fails when they differ). Then write a migration that changes the string in +the apps' scripts, and bump `template_version`. + +## If something does not work + +- `menuinst_debug.log` in the app's install folder says what the installer did with your tools. +- `labconstrictor-tools doctor` checks the Tools installation, and `labconstrictor-tools logs` shows its log. diff --git a/.template_sync/resources/v0_1_31_to_v0_1_32/previous/.tools/docs/tools_bridge.md b/.template_sync/resources/v0_1_31_to_v0_1_32/previous/.tools/docs/tools_bridge.md new file mode 100644 index 0000000..c557edb --- /dev/null +++ b/.template_sync/resources/v0_1_31_to_v0_1_32/previous/.tools/docs/tools_bridge.md @@ -0,0 +1,59 @@ +# Expose your app's tools to Napari, Fiji and QuPath (optional, experimental) + +If your repository ships Python code (see [Upload external code](external_code_upload.md)), you can declare some of its functions +as **tools**. After installation they appear in a generic **Napari** widget, a generic **Fiji** command and a generic **QuPath** command, and work from the +command line, with forms generated automatically from the function signatures. Nothing changes for apps that do not declare tools. + +1. Add a module named `_lc_tools` next to your package under `src/` (so `src/mytool_lc_tools/__init__.py` for + the package `mytool`). Declare tools in it with typed functions, importing your science code **inside** the functions: + + ```python + from typing import Annotated + from labconstrictor_tools import Image, ImageOut, Min, tool + + @tool("Gaussian blur") + def blur(image: Image, sigma: Annotated[float, Min(0)] = 2.0) -> ImageOut: + from mytool.filters import gaussian + return gaussian(image, sigma) + ``` + + Keep the module light: it is imported to read the tool list, so heavy imports at the top slow every start. + **Import `labconstrictor_tools` only in the tools module if you can.** Since template 0.1.17 the installer installs `labconstrictor-tools` *before* it checks that + your package can be imported, so a package that imports `labconstrictor_tools` at module level no longer stops the installation. It is still better practice to import it lazily (inside functions) + or only in `_lc_tools`: the rest of your package then also works where Tools is not installed (a notebook run on Colab, a copy of the package used elsewhere, a failed Tools install). +2. The installer (`post_install`) detects the module, installs `labconstrictor-tools` and registers the app + (`labconstrictor-tools register ...`). `pre_uninstall` unregisters it. A failure in this step is logged to + `menuinst_debug.log` and never fails the installation. + **Order in `post_install`.** (1) your package is installed, (2) if it ships `_lc_tools`, `labconstrictor-tools` is installed, (3) the package import check runs, (4) the app is registered. + Installing Tools before the import check is what lets your package import `labconstrictor_tools` at module level. A failed Tools install is a `WARNING` in `menuinst_debug.log` + and the registration is skipped; the installation continues, unless your package needs Tools to be imported (then the import check fails, as it should). + **Where `labconstrictor-tools` comes from.** It is not on PyPI yet, so by default the installer downloads the GitHub archive of a **pinned release tag**, + `https://github.com/CellMigrationLab/LabConstrictor-Tools/archive/refs/tags/v0.3.0-alpha.2.zip` (a plain zip: git is not needed on the user's computer). + Set the environment variable `LC_TOOLS_SPEC` when the installer runs to install it from somewhere else (a wheel, a git URL, a mirror, or the + name `labconstrictor-tools` once it is published on PyPI); it overrides the pin completely. + **Pinned (important).** Two installers built from the same app release get the same version of the tools package, and a change to Tools `main` + does not reach new installations until the pin is moved on purpose. + **How to move the pin.** The tag name is written in one place per script: the variable `LC_TOOLS_PIN` (`LC_TOOLS_PIN="v0.3.0-alpha.2"` in + `app/bash_bat_scripts/post_install.sh`, `SET "LC_TOOLS_PIN=v0.3.0-alpha.2"` in `post_install.bat`). To use a new release: create and test the tag in + LabConstrictor-Tools (procedure in its `docs/OPERATIONS.md`), change that string in both scripts and in the copies under + `.template_sync/resources/` of the latest migration (the test `test_resources_are_identical_to_the_template_files` fails when they differ), + update the tag in this paragraph, and bump `template_version` so apps receive the change. Apps already migrated need a new migration to change the + string in their own scripts. +3. Test your tools before releasing: `labconstrictor-tools check --module mytool_lc_tools` and + `labconstrictor-tools test --module mytool_lc_tools --cases lc_tests/cases.json`. +4. Install the Napari plugin (`napari-labconstrictor`), the Fiji plugin (`labconstrictor-fiji`) or the QuPath extension once per machine. None of them is on PyPI or an update site yet: + see the READMEs of [LabConstrictor-napari](https://github.com/CellMigrationLab/LabConstrictor-napari), + [LabConstrictor-Fiji](https://github.com/CellMigrationLab/LabConstrictor-Fiji) and [LabConstrictor-QuPath](https://github.com/CellMigrationLab/LabConstrictor-QuPath) for the install steps. +5. Optional: make a long form readable and rich with markers (the authoring guide in the Tools repository lists them all): + - layout: `Group("...")`, `Advanced()`, `Collapsed()`, `EnabledWhen(...)`; + - input widgets: `Widget("slider")` for a bounded number and `Widget("radio")` for a short list of choices; + - `PickChannel()` to let the person choose one channel of a multi-channel image (your function receives that channel as a 2D array); + - `ChoicesFrom("other_tool")` to fill a dropdown from another tool of yours (for example the available devices); + - `RegionOf("image")` (optional labels input) to run on the selection in the host (Napari Shapes layer, Fiji ROI, QuPath annotations); + - outputs: `ImageOut`, `LabelsOut`, `TableOut`, `Scalars`, `MessageOut`, `PointsOut` and `ShapesOut` (polygons: Napari shapes layer, Fiji ROIs, QuPath annotations); + - say "nothing found" with `ToolError("no_match", ...)`. + Napari, Fiji and QuPath do not support every feature in the same way: the table "What each host does with each feature" in `docs/HOST_FEATURES.md` of the Tools repository is the reference. +Documentation and source: https://github.com/CellMigrationLab/LabConstrictor-Tools. +The registered version is read from the `version:` line of `construct.yaml`. The Windows hook (`post_install.bat`) runs in the template's automated tests on a Windows +machine, and people have installed apps on Windows and macOS from a clean system. +Troubleshooting: `labconstrictor-tools doctor`, `labconstrictor-tools logs`, and `~/.labconstrictor/logs/labconstrictor.log`. diff --git a/.tools/docs/README.md b/.tools/docs/README.md index 03cd375..a819601 100644 --- a/.tools/docs/README.md +++ b/.tools/docs/README.md @@ -21,7 +21,7 @@ This file temporarily lists all internal LabConstrictor documentation. After you - [Customise the installer images](installer_images.md) - [Describe your app for the App Centre](app_manifest.md) - [Upload external code, and publish it on PyPI (optional)](external_code_upload.md) -- [Expose tools to Napari, Fiji and QuPath (experimental)](tools_bridge.md) +- [Expose tools to napari, Fiji and QuPath (experimental)](tools_bridge.md) ## Keep your app up to date (optional) diff --git a/.tools/docs/install.md b/.tools/docs/install.md index b23b6ef..d324656 100644 --- a/.tools/docs/install.md +++ b/.tools/docs/install.md @@ -38,7 +38,9 @@ Installing takes about 6-8 minutes and you only do it once. You need an internet ## Where the app is listed -If the app ships tools for Napari, Fiji or QuPath, the installer registers them with LabConstrictor Tools and passes the `hosts:` line of the app's `labconstrictor-app.yaml` (the installer bundles that file). A host lists the app only if the line names it: with `hosts: [notebook, napari]` the app is listed in Napari, and not in Fiji or QuPath. Without the file, or without a `hosts:` line, the app is registered without hosts, every host lists it, and `menuinst_debug.log` in the install folder says so (`'' declares no hosts, so it is listed in every host; ...`). +If the app ships tools for napari, Fiji or QuPath, the installer registers them with LabConstrictor Tools and passes the `hosts:` line of the app's `labconstrictor-app.yaml` (the installer bundles that file). A host lists the app only if the line names it: with `hosts: [notebook, napari]` the app is listed in napari, and not in Fiji or QuPath. Without the file, or without a `hosts:` line, the app is registered without hosts, every host lists it, and `menuinst_debug.log` in the install folder says so (`'' declares no hosts, so it is listed in every host; ...`). + +To run the tools, install the plugin for your image software once: see [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). ## Next diff --git a/.tools/docs/migration_0_1_32.md b/.tools/docs/migration_0_1_32.md new file mode 100644 index 0000000..37300f6 --- /dev/null +++ b/.tools/docs/migration_0_1_32.md @@ -0,0 +1,44 @@ +# Template 0.1.32: the user docs link to the guide that owns a topic + +Design note for the 0.1.32 migration (`.template_sync/migrations/v0_1_31_to_v0_1_32.py`). How a change reaches an installed copy is described in [migration_0_1_16.md](migration_0_1_16.md): a new installer is needed, nothing edits an existing install. + +## 1. The problem + +The LabConstrictor documentation is spread over several repositories, and the same steps were written in several of them. Copies drift: on 2026-11-16 the install steps of the Fiji plugin were on 8 pages, those of the napari plugin on 7, and version numbers of the plugins and of LabConstrictor Tools on 22. The rule agreed for the whole project is that each topic is written on one page, its owner, and every other page links to it. The website ([LabConstrictor-Site](https://cellmigrationlab.github.io/LabConstrictor-Site/)) publishes the owner pages, and it imports the template's `.tools/docs` as its "Build an app" guides. + +The owners of the topics this template's docs touched: + +| Topic | Owner | +|---|---| +| Install an app; what the installer does; where an app declares its tools | This template (`install.md`, `tools_bridge.md`) | +| Install and open the napari plugin, the Fiji plugin, the QuPath extension | Each plugin's repository (`docs/user-guide.md`), published on the website as `/guides/napari/`, `/guides/fiji/`, `/guides/qupath/` | +| Run an app's tools in image software (overview) | LabConstrictor-Tools `docs/user-guide.md`, published as `/guides/image-software/` | +| Write and test a tool (inputs, outputs, form markers, `check` and `test`) | LabConstrictor-Tools `docs/AUTHORING.md` | + +`tools_bridge.md` repeated the plugins' install situation, the list of form markers, the test commands and the Tools pin's version (`v0.3.0-alpha.2`, also in the step that tells maintainers to update "the tag in this paragraph"). + +## 2. What changes + +| File | Change | +|---|---| +| `.tools/docs/tools_bridge.md` | Rewritten around what the template owns: where to declare tools, the order of the installer's steps, the Tools pin (where it is set, `LC_TOOLS_SPEC`, how maintainers move it), what to look at when something fails. It links to the owner guides for writing and testing tools and for the plugins. The pin's version is no longer written in the docs: the scripts are the only place it is set. | +| `.tools/docs/install.md` | "Where the app is listed" writes napari in lower case, as the project does, and ends with a link to the guide that says how to run the tools. | +| `.tools/docs/README.md` | The entry of the tools guide writes napari in lower case. | + +The template's own README and the other user pages of `.tools/docs` had no copies of these topics. `app_manifest.md` names a plugin version only as an example value of `host_requirements`, which is the template's own field. + +## 3. What the migration does + +Every step is independent, idempotent, never deletes, never raises for a customised file (the sync pull request is still created) and keeps the line endings of each file. + +* **`tools_bridge.md`** is replaced by the 0.1.32 guide when it is still the 0.1.31 template file (compared with LF line endings; the frozen copies are in `.template_sync/resources/v0_1_31_to_v0_1_32/`). A customised guide is left as it is (`SKIPPED`). +* **`install.md`** and **`README.md`**: each change replaces one exact piece of 0.1.31 text. A file where that text is not found is left as it is (`SKIPPED`). + +## 4. Adopting it + +Take this template version (the synchronization pull request). Nothing else is needed: the docs change only. Users see the new pages on GitHub at once and in the app with its next release. + +## 5. What is checked here + +* Tests (`tests/test_template_sync_0_1_32.py`): the resources are the live guide and the 0.1.31 one; the live files are the 0.1.31 files migrated; the migration on 0.1.31 files with LF and CRLF line endings, on customised files, on a repository without the files, and a second run; the sync chain from 0.1.31. +* The migration chain was run on copies of real apps. diff --git a/.tools/docs/tools_bridge.md b/.tools/docs/tools_bridge.md index c557edb..9599e53 100644 --- a/.tools/docs/tools_bridge.md +++ b/.tools/docs/tools_bridge.md @@ -1,11 +1,24 @@ -# Expose your app's tools to Napari, Fiji and QuPath (optional, experimental) +# Expose your app's tools to napari, Fiji and QuPath (optional, experimental) If your repository ships Python code (see [Upload external code](external_code_upload.md)), you can declare some of its functions -as **tools**. After installation they appear in a generic **Napari** widget, a generic **Fiji** command and a generic **QuPath** command, and work from the -command line, with forms generated automatically from the function signatures. Nothing changes for apps that do not declare tools. +as **tools**. After installation, people can run them in napari, Fiji and QuPath and from the command line, with forms made from the +function signatures. Nothing changes for apps that do not declare tools. + +This page covers what the template does: where you declare the tools and what the installer does with them. Two other guides cover the rest: + +- [Writing tools](https://github.com/CellMigrationLab/LabConstrictor-Tools/blob/main/docs/AUTHORING.md), in LabConstrictor-Tools: the inputs + and outputs a tool can have, how to lay out its form, what each program supports, and how to test a tool. +- [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/): what the people + who install your app do to run its tools, with the install steps of the + [napari plugin](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/napari/), the + [Fiji plugin](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/fiji/) and the + [QuPath extension](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/qupath/). + +## Declare your tools 1. Add a module named `_lc_tools` next to your package under `src/` (so `src/mytool_lc_tools/__init__.py` for - the package `mytool`). Declare tools in it with typed functions, importing your science code **inside** the functions: + the package `mytool`). The installer registers tools only from a module with exactly this name. Declare tools in it with typed + functions, and import your science code **inside** the functions: ```python from typing import Annotated @@ -18,42 +31,51 @@ command line, with forms generated automatically from the function signatures. N ``` Keep the module light: it is imported to read the tool list, so heavy imports at the top slow every start. - **Import `labconstrictor_tools` only in the tools module if you can.** Since template 0.1.17 the installer installs `labconstrictor-tools` *before* it checks that - your package can be imported, so a package that imports `labconstrictor_tools` at module level no longer stops the installation. It is still better practice to import it lazily (inside functions) - or only in `_lc_tools`: the rest of your package then also works where Tools is not installed (a notebook run on Colab, a copy of the package used elsewhere, a failed Tools install). -2. The installer (`post_install`) detects the module, installs `labconstrictor-tools` and registers the app - (`labconstrictor-tools register ...`). `pre_uninstall` unregisters it. A failure in this step is logged to - `menuinst_debug.log` and never fails the installation. - **Order in `post_install`.** (1) your package is installed, (2) if it ships `_lc_tools`, `labconstrictor-tools` is installed, (3) the package import check runs, (4) the app is registered. - Installing Tools before the import check is what lets your package import `labconstrictor_tools` at module level. A failed Tools install is a `WARNING` in `menuinst_debug.log` - and the registration is skipped; the installation continues, unless your package needs Tools to be imported (then the import check fails, as it should). - **Where `labconstrictor-tools` comes from.** It is not on PyPI yet, so by default the installer downloads the GitHub archive of a **pinned release tag**, - `https://github.com/CellMigrationLab/LabConstrictor-Tools/archive/refs/tags/v0.3.0-alpha.2.zip` (a plain zip: git is not needed on the user's computer). - Set the environment variable `LC_TOOLS_SPEC` when the installer runs to install it from somewhere else (a wheel, a git URL, a mirror, or the - name `labconstrictor-tools` once it is published on PyPI); it overrides the pin completely. - **Pinned (important).** Two installers built from the same app release get the same version of the tools package, and a change to Tools `main` - does not reach new installations until the pin is moved on purpose. - **How to move the pin.** The tag name is written in one place per script: the variable `LC_TOOLS_PIN` (`LC_TOOLS_PIN="v0.3.0-alpha.2"` in - `app/bash_bat_scripts/post_install.sh`, `SET "LC_TOOLS_PIN=v0.3.0-alpha.2"` in `post_install.bat`). To use a new release: create and test the tag in - LabConstrictor-Tools (procedure in its `docs/OPERATIONS.md`), change that string in both scripts and in the copies under - `.template_sync/resources/` of the latest migration (the test `test_resources_are_identical_to_the_template_files` fails when they differ), - update the tag in this paragraph, and bump `template_version` so apps receive the change. Apps already migrated need a new migration to change the - string in their own scripts. -3. Test your tools before releasing: `labconstrictor-tools check --module mytool_lc_tools` and - `labconstrictor-tools test --module mytool_lc_tools --cases lc_tests/cases.json`. -4. Install the Napari plugin (`napari-labconstrictor`), the Fiji plugin (`labconstrictor-fiji`) or the QuPath extension once per machine. None of them is on PyPI or an update site yet: - see the READMEs of [LabConstrictor-napari](https://github.com/CellMigrationLab/LabConstrictor-napari), - [LabConstrictor-Fiji](https://github.com/CellMigrationLab/LabConstrictor-Fiji) and [LabConstrictor-QuPath](https://github.com/CellMigrationLab/LabConstrictor-QuPath) for the install steps. -5. Optional: make a long form readable and rich with markers (the authoring guide in the Tools repository lists them all): - - layout: `Group("...")`, `Advanced()`, `Collapsed()`, `EnabledWhen(...)`; - - input widgets: `Widget("slider")` for a bounded number and `Widget("radio")` for a short list of choices; - - `PickChannel()` to let the person choose one channel of a multi-channel image (your function receives that channel as a 2D array); - - `ChoicesFrom("other_tool")` to fill a dropdown from another tool of yours (for example the available devices); - - `RegionOf("image")` (optional labels input) to run on the selection in the host (Napari Shapes layer, Fiji ROI, QuPath annotations); - - outputs: `ImageOut`, `LabelsOut`, `TableOut`, `Scalars`, `MessageOut`, `PointsOut` and `ShapesOut` (polygons: Napari shapes layer, Fiji ROIs, QuPath annotations); - - say "nothing found" with `ToolError("no_match", ...)`. - Napari, Fiji and QuPath do not support every feature in the same way: the table "What each host does with each feature" in `docs/HOST_FEATURES.md` of the Tools repository is the reference. -Documentation and source: https://github.com/CellMigrationLab/LabConstrictor-Tools. -The registered version is read from the `version:` line of `construct.yaml`. The Windows hook (`post_install.bat`) runs in the template's automated tests on a Windows -machine, and people have installed apps on Windows and macOS from a clean system. -Troubleshooting: `labconstrictor-tools doctor`, `labconstrictor-tools logs`, and `~/.labconstrictor/logs/labconstrictor.log`. +2. Import `labconstrictor_tools` only in `_lc_tools`, or inside functions, if you can. The rest of your package then also works + where LabConstrictor Tools is not installed: a notebook run on Google Colab, a copy of the package used elsewhere, or an installation where + Tools failed to install. An import at the top of your package does not stop the installation, because the installer installs Tools before + it checks that your package can be imported. +3. Name the programs your tools work in under `hosts:` in `labconstrictor-app.yaml`: see [Describe your app for the App Centre](app_manifest.md). +4. Test your tools before you publish a release, as [Writing tools](https://github.com/CellMigrationLab/LabConstrictor-Tools/blob/main/docs/AUTHORING.md) + shows (`labconstrictor-tools check` and `labconstrictor-tools test`). + +## What the installer does + +The installer's `post_install` step: + +1. installs your package; +2. if your package has a `_lc_tools` module, installs LabConstrictor Tools; +3. checks that your package can be imported; +4. registers the app (`labconstrictor-tools register ...`) with the version from the `version:` line of `construct.yaml` and the hosts of + `labconstrictor-app.yaml`. + +When the app is uninstalled, `pre_uninstall` unregisters it. + +A failure in step 2 or 4 is written as a `WARNING` to `menuinst_debug.log` in the install folder, the registration is skipped, and the +installation goes on. The one exception is a package that needs Tools to be imported: then the import check of step 3 fails, as it should. + +The Windows step (`post_install.bat`) runs in the template's automated tests on a Windows machine, and people have installed apps on Windows +and macOS from a clean system. + +### Which LabConstrictor Tools the installer installs + +LabConstrictor Tools is not on PyPI yet. The installer downloads the GitHub archive of one release tag of LabConstrictor-Tools, a plain zip +file, so the user's computer does not need git. The tag is pinned: two installers built from the same app release install the same Tools, +and a change to Tools does not reach new installations until the pin is moved on purpose. Template updates move the pin in your app. + +The tag is the value of `LC_TOOLS_PIN` in both scripts: +[app/bash_bat_scripts/post_install.sh](../../app/bash_bat_scripts/post_install.sh) (`LC_TOOLS_PIN="..."`) and +[app/bash_bat_scripts/post_install.bat](../../app/bash_bat_scripts/post_install.bat) (`SET "LC_TOOLS_PIN=..."`). + +To install Tools from somewhere else, set the environment variable `LC_TOOLS_SPEC` when the installer runs: a wheel, a git URL, a mirror, or +the name `labconstrictor-tools` once it is on PyPI. It replaces the pin completely. + +**Move the pin (template maintainers).** Create and test the tag in LabConstrictor-Tools (the procedure is in its `docs/OPERATIONS.md`). +Change `LC_TOOLS_PIN` in both scripts of the template, and in the copies under `.template_sync/resources/` of the latest migration if it has +them (the test `test_resources_are_identical_to_the_template_files` fails when they differ). Then write a migration that changes the string in +the apps' scripts, and bump `template_version`. + +## If something does not work + +- `menuinst_debug.log` in the app's install folder says what the installer did with your tools. +- `labconstrictor-tools doctor` checks the Tools installation, and `labconstrictor-tools logs` shows its log. diff --git a/tests/_v0_1_31.py b/tests/_v0_1_31.py index d4feda5..6fb4d85 100644 --- a/tests/_v0_1_31.py +++ b/tests/_v0_1_31.py @@ -4,7 +4,7 @@ the requirements check to release_constructor.yml and the safe notebook update to Welcome_template.ipynb. The resources of the older migrations are frozen; `before_0_1_31` gives the bytes of a live file without the 0.1.31 change, using the migration's own constants (the frozen 0.1.30 copies for merge_requirements.py and the Welcome template), so their tests keep checking what they checked. The 0.1.31 -changes are tested in test_template_sync_0_1_31.py. +changes are tested in test_template_sync_0_1_31.py. The later changes of 0.1.32 are taken out first (tests/_v0_1_32.py). """ from __future__ import annotations @@ -12,6 +12,8 @@ from pathlib import Path from types import ModuleType +from _v0_1_32 import before_0_1_32 + ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_30_to_v0_1_31.py" WELCOME_0_1_30 = ROOT / "tests/fixtures/template_0_1_30/Welcome_template.ipynb" @@ -28,6 +30,7 @@ def _migration() -> ModuleType: def before_0_1_31(relative: Path | str, data: bytes) -> bytes: """`data` (a live template file at `relative`) without the change 0.1.31 made to it; any other file is returned as it is.""" + data = before_0_1_32(relative, data) migration = _migration() relative = Path(relative) if relative == migration.MERGE: diff --git a/tests/_v0_1_32.py b/tests/_v0_1_32.py new file mode 100644 index 0000000..510d92f --- /dev/null +++ b/tests/_v0_1_32.py @@ -0,0 +1,44 @@ +"""Helper of the tests: a live template file as it was before template 0.1.32. + +Template 0.1.32 rewrote tools_bridge.md around what the template owns (it links to the owner guides of the plugins and of LabConstrictor +Tools), and changed one paragraph of install.md and one entry of the docs README. The resources of the older migrations are frozen; +`before_0_1_32` gives the bytes of a live file without the 0.1.32 change (the frozen 0.1.31 copy for tools_bridge.md, the migration's own +edits undone for the others), so their tests keep checking what they checked. The 0.1.32 changes are tested in test_template_sync_0_1_32.py. +""" +from __future__ import annotations + +import importlib.util +from pathlib import Path +from types import ModuleType + +ROOT = Path(__file__).resolve().parents[1] +MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_31_to_v0_1_32.py" + + +def _migration() -> ModuleType: + spec = importlib.util.spec_from_file_location("migration_0_1_32_for_older_tests", MIGRATION_PATH) + if spec is None or spec.loader is None: + raise RuntimeError(f"Unable to load {MIGRATION_PATH}") + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +def before_0_1_32(relative: Path | str, data: bytes) -> bytes: + """`data` (a live template file at `relative`) without the change 0.1.32 made to it; any other file is returned as it is.""" + migration = _migration() + relative = Path(relative) + if relative not in migration.FILES: + return data + text = data.decode("utf-8") + newline = "\r\n" if "\r\n" in text else "\n" + if relative in migration.WHOLE_FILES: + # Only the 0.1.32 file is swapped back: older helpers run this chain again on text that is already older (tests/_v0_1_20.py). + if text.replace("\r\n", "\n") != (migration.RESOURCE_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n"): + return data + text = (migration.PREVIOUS_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n") + else: + text = text.replace("\r\n", "\n") + for old, new in reversed(migration.EDITS[relative]): + text = text.replace(new, old, 1) + return text.replace("\n", newline).encode("utf-8") diff --git a/tests/test_template_sync_0_1_17.py b/tests/test_template_sync_0_1_17.py index 3bd3e9f..4617027 100644 --- a/tests/test_template_sync_0_1_17.py +++ b/tests/test_template_sync_0_1_17.py @@ -20,6 +20,7 @@ from _hosts import strip_hosts from _v0_1_20 import before_0_1_20 from _v0_1_28 import before_0_1_28 +from _v0_1_32 import before_0_1_32 ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_16_to_v0_1_17.py" @@ -137,7 +138,8 @@ def test_chains_from_every_older_version_reach_0_1_17(self) -> None: def test_the_docs_are_linked_and_describe_the_new_order(self) -> None: # the design note is linked from its migration (DOCS_URL); since 0.1.29 the docs README no longer lists design notes self.assertIn(".tools/docs/migration_0_1_17.md", (ROOT / ".template_sync/migrations/v0_1_16_to_v0_1_17.py").read_text(encoding="utf-8")) - bridge = (ROOT / ".tools/docs/tools_bridge.md").read_text(encoding="utf-8") + # the guide as 0.1.31 had it: 0.1.32 rewrote it around the owner guides (tests/_v0_1_32.py) + bridge = before_0_1_32(".tools/docs/tools_bridge.md", (ROOT / ".tools/docs/tools_bridge.md").read_bytes()).decode("utf-8") self.assertIn("before* it checks that", bridge) self.assertIn("lazily", bridge, "the advice to import labconstrictor_tools lazily stays") diff --git a/tests/test_template_sync_0_1_28.py b/tests/test_template_sync_0_1_28.py index 8727682..534154c 100644 --- a/tests/test_template_sync_0_1_28.py +++ b/tests/test_template_sync_0_1_28.py @@ -13,6 +13,8 @@ from pathlib import Path from types import ModuleType +from _v0_1_32 import before_0_1_32 + ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_27_to_v0_1_28.py" @@ -31,6 +33,11 @@ def load(path: Path, name: str) -> ModuleType: OLD, NEW = MIGRATION.OLD_PIN, MIGRATION.NEW_PIN +def live(relative: Path) -> bytes: + """The live template file without the later change of 0.1.32 (the guide no longer names the pin: tests/_v0_1_32.py).""" + return before_0_1_32(relative, (ROOT / relative).read_bytes()) + + class TemplateTests(unittest.TestCase): def test_the_template_pins_the_new_tag_once_per_script_and_names_it_in_the_guide(self) -> None: for relative in (SH, BAT): @@ -38,8 +45,8 @@ def test_the_template_pins_the_new_tag_once_per_script_and_names_it_in_the_guide with self.subTest(file=str(relative)): self.assertEqual(text.count(NEW), 1) self.assertNotIn(OLD, text) - self.assertIn(f"archive/refs/tags/{NEW}.zip", (ROOT / DOC).read_text(encoding="utf-8")) - self.assertNotIn(OLD, (ROOT / DOC).read_text(encoding="utf-8")) + self.assertIn(f"archive/refs/tags/{NEW}.zip", live(DOC).decode("utf-8")) + self.assertNotIn(OLD, live(DOC).decode("utf-8")) self.assertIn("\r\n", (ROOT / BAT).read_bytes().decode("utf-8"), "post_install.bat stays CRLF") def test_the_manifest_lists_the_migration_and_the_version(self) -> None: @@ -55,7 +62,7 @@ def setUp(self) -> None: for relative in (SH, BAT, DOC): target = self.repo / relative target.parent.mkdir(parents=True, exist_ok=True) - target.write_bytes((ROOT / relative).read_bytes().replace(NEW.encode(), OLD.encode())) + target.write_bytes(live(relative).replace(NEW.encode(), OLD.encode())) def tearDown(self) -> None: shutil.rmtree(self.repo, ignore_errors=True) @@ -70,7 +77,7 @@ def test_an_app_of_0_1_27_gets_the_template_files_and_a_second_run_changes_nothi log = self.run_migration() for relative in (SH, BAT, DOC): with self.subTest(file=str(relative)): - self.assertEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes()) + self.assertEqual((self.repo / relative).read_bytes(), live(relative)) self.assertEqual(log.count(f"updated: Tools pin {OLD} -> {NEW}"), 2, log) self.assertIn("3 file(s) changed", log) self.assertIn("no repository changes were required", self.run_migration()) diff --git a/tests/test_template_sync_0_1_30.py b/tests/test_template_sync_0_1_30.py index 3ded2b4..c92fe99 100644 --- a/tests/test_template_sync_0_1_30.py +++ b/tests/test_template_sync_0_1_30.py @@ -15,6 +15,7 @@ from types import ModuleType from _v0_1_30 import before_0_1_30 +from _v0_1_32 import before_0_1_32 ROOT = Path(__file__).resolve().parents[1] @@ -43,6 +44,11 @@ def lf(path: Path) -> str: return path.read_bytes().decode("utf-8").replace("\r\n", "\n") +def at_0_1_31(relative: Path) -> bytes: + """The live template file without the later changes of 0.1.32 (tools_bridge.md and install.md: tests/_v0_1_32.py).""" + return before_0_1_32(relative, (ROOT / relative).read_bytes()) + + class TemplateTests(unittest.TestCase): def test_the_manifest_lists_the_migration_and_the_version(self) -> None: text = (ROOT / ".template_sync/manifest.yaml").read_text(encoding="utf-8") @@ -61,7 +67,7 @@ def test_no_live_template_file_names_the_old_address(self) -> None: def test_the_live_files_hold_each_correction_once_and_no_old_text(self) -> None: for relative, edits in MIGRATION.EDITS.items(): - text = lf(ROOT / relative) + text = at_0_1_31(relative).decode("utf-8").replace("\r\n", "\n") for old, new in edits: with self.subTest(file=str(relative), new=new[:40]): self.assertEqual(text.count(new), 1) @@ -96,11 +102,11 @@ def run_migration(self) -> str: def test_an_app_of_0_1_29_gets_the_template_files_and_a_second_run_changes_nothing(self) -> None: for relative in TEMPLATE_FILES: - self.assertNotEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes(), relative) + self.assertNotEqual((self.repo / relative).read_bytes(), at_0_1_31(relative), relative) log = self.run_migration() for relative in TEMPLATE_FILES: with self.subTest(file=str(relative)): - self.assertEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes()) + self.assertEqual((self.repo / relative).read_bytes(), at_0_1_31(relative)) self.assertIn(f"{len(MIGRATION.FILES)} file(s) changed", log) self.assertIn("no repository changes were required", self.run_migration()) diff --git a/tests/test_template_sync_0_1_32.py b/tests/test_template_sync_0_1_32.py new file mode 100644 index 0000000..4b0f391 --- /dev/null +++ b/tests/test_template_sync_0_1_32.py @@ -0,0 +1,216 @@ +"""Tests of the 0.1.32 migration: the user docs link to the guide that owns a topic (plugin install steps, writing tools).""" +from __future__ import annotations + +import importlib.util +import os +import re +import shutil +import subprocess +import sys +import tempfile +import unittest +from contextlib import redirect_stdout +from io import StringIO +from pathlib import Path +from types import ModuleType + +from _v0_1_32 import before_0_1_32 + + +ROOT = Path(__file__).resolve().parents[1] +MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_31_to_v0_1_32.py" +SYNC_PATH = ROOT / ".template_sync/sync.py" +DOCS = ROOT / ".tools/docs" +SITE = "https://cellmigrationlab.github.io/LabConstrictor-Site/" +AUTHORING = "https://github.com/CellMigrationLab/LabConstrictor-Tools/blob/main/docs/AUTHORING.md" + + +def load(path: Path, name: str) -> ModuleType: + spec = importlib.util.spec_from_file_location(name, path) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +MIGRATION = load(MIGRATION_PATH, "migration_0_1_32") + + +def lf(path: Path) -> str: + return path.read_bytes().decode("utf-8").replace("\r\n", "\n") + + +def old(relative: Path) -> bytes: + """The 0.1.31 file: the live file without the 0.1.32 change.""" + return before_0_1_32(relative, (ROOT / relative).read_bytes()) + + +def user_pages() -> list[Path]: + """The user-facing pages of .tools/docs (the migration_*.md design notes are history).""" + return sorted(path for path in DOCS.glob("*.md") if not path.name.startswith("migration_")) + + +class TemplateTests(unittest.TestCase): + def test_the_manifest_lists_the_migration_and_the_new_version(self) -> None: + text = lf(ROOT / ".template_sync/manifest.yaml") + self.assertRegex(text, r"template_version: 0\.1\.(3[2-9]|[4-9][0-9])\b") + self.assertIn("script: migrations/v0_1_31_to_v0_1_32.py", text) + + def test_chains_from_older_versions_reach_0_1_32(self) -> None: + sync = load(SYNC_PATH, "sync_for_0_1_32") + manifest = sync.parse_manifest(ROOT / ".template_sync/manifest.yaml") + for start in ("0.0.0", "0.1.16", "0.1.24", "0.1.31"): + self.assertEqual(sync.resolve_migration_chain(manifest["migrations"], start, "0.1.32")[-1]["to"], "0.1.32", start) + + def test_the_design_note_exists_and_the_migration_links_it(self) -> None: + self.assertTrue((DOCS / "migration_0_1_32.md").is_file()) + self.assertIn(".tools/docs/migration_0_1_32.md", MIGRATION.DOCS_URL) + self.assertNotIn("migration_0_1_32.md", lf(DOCS / "README.md"), "the docs README does not list design notes") + + def test_the_resources_are_the_live_guide_and_the_0_1_31_one(self) -> None: + for relative in MIGRATION.WHOLE_FILES: + with self.subTest(file=str(relative)): + self.assertEqual((MIGRATION.RESOURCE_ROOT / relative).read_bytes(), (ROOT / relative).read_bytes()) + self.assertNotEqual(lf(MIGRATION.PREVIOUS_ROOT / relative), lf(ROOT / relative)) + + def test_the_live_files_are_the_0_1_31_files_migrated(self) -> None: + for relative in MIGRATION.EDITS: + with self.subTest(file=str(relative)): + text, applied, missing = MIGRATION.apply_edits(old(relative).decode("utf-8"), MIGRATION.EDITS[relative]) + self.assertEqual((applied, missing), (len(MIGRATION.EDITS[relative]), 0)) + self.assertEqual(text, lf(ROOT / relative)) + + def test_the_tools_guide_links_the_owner_guides(self) -> None: + text = lf(ROOT / MIGRATION.TOOLS_DOC) + for address in (f"{SITE}guides/image-software/", f"{SITE}guides/napari/", f"{SITE}guides/fiji/", f"{SITE}guides/qupath/", AUTHORING): + with self.subTest(address=address): + self.assertIn(f"]({address})", text) + self.assertIn(f"]({SITE}guides/image-software/)", lf(ROOT / MIGRATION.INSTALL_DOC)) + + def test_no_user_page_repeats_the_plugin_install_steps_or_a_version_pin(self) -> None: + pin = re.search(r'LC_TOOLS_PIN="([^"]+)"', lf(ROOT / "app/bash_bat_scripts/post_install.sh")) + assert pin is not None + repeated = ( + pin.group(1), # the Tools pin: set in the scripts only + "LabConstrictor-Tools/archive/refs/tags/", # the address the pin builds + "pip install napari-labconstrictor", # napari plugin install step + "labconstrictor-fiji.jar", # Fiji plugin install step + "update site", # Fiji install situation + "Extension Manager", # QuPath install step + "for the install steps", # the old pointer to the plugin READMEs + ) + for path in [*user_pages(), ROOT / "README.md"]: + text = lf(path) + for needle in repeated: + with self.subTest(file=path.name, text=needle): + self.assertNotIn(needle, text) + + def test_the_pin_is_still_set_in_both_scripts(self) -> None: + self.assertRegex(lf(ROOT / "app/bash_bat_scripts/post_install.sh"), r'\n\s*LC_TOOLS_PIN="v[^"]+"\n') + self.assertRegex(lf(ROOT / "app/bash_bat_scripts/post_install.bat"), r'\nSET "LC_TOOLS_PIN=v[^"]+"\n') + + def test_the_relative_links_of_the_changed_pages_resolve(self) -> None: + for relative in MIGRATION.FILES: + for target in re.findall(r"\]\(([^)#\s]+)(?:#[^)]*)?\)", lf(ROOT / relative)): + if "://" in target: + continue + with self.subTest(file=str(relative), target=target): + self.assertTrue(((ROOT / relative).parent / target).resolve().exists()) + + +class MigrationTests(unittest.TestCase): + def setUp(self) -> None: + self.repo = Path(tempfile.mkdtemp(prefix="lc_0_1_32_")) + for relative in MIGRATION.FILES: + self.put(relative, old(relative)) + + def tearDown(self) -> None: + shutil.rmtree(self.repo, ignore_errors=True) + + def put(self, relative: Path, data: bytes) -> Path: + target = self.repo / relative + target.parent.mkdir(parents=True, exist_ok=True) + target.write_bytes(data) + return target + + def run_migration(self) -> str: + out = StringIO() + with redirect_stdout(out): + MIGRATION.migrate(self.repo, {}) + return out.getvalue() + + def test_an_app_of_0_1_31_gets_the_template_files_and_a_second_run_changes_nothing(self) -> None: + for relative in MIGRATION.FILES: + self.assertNotEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes(), relative) + log = self.run_migration() + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + self.assertEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes()) + self.assertIn(f"done: {len(MIGRATION.FILES)} file(s) changed", log) + self.assertNotIn("SKIPPED", log) + again = self.run_migration() + self.assertIn("no repository changes were required", again) + self.assertNotIn("SKIPPED", again) + + def test_crlf_is_kept(self) -> None: + for relative in MIGRATION.FILES: + self.put(relative, old(relative).replace(b"\n", b"\r\n")) + self.run_migration() + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + raw = (self.repo / relative).read_bytes() + self.assertNotIn(b"\n", raw.replace(b"\r\n", b"")) + self.assertEqual(raw.replace(b"\r\n", b"\n"), (ROOT / relative).read_bytes()) + + def test_a_customised_guide_is_skipped(self) -> None: + guide = self.put(MIGRATION.TOOLS_DOC, old(MIGRATION.TOOLS_DOC) + b"\nOur own note.\n") + before = guide.read_bytes() + log = self.run_migration() + self.assertIn(f"{MIGRATION.TOOLS_DOC}: SKIPPED: customised (not the 0.1.31 template file)", log) + self.assertEqual(guide.read_bytes(), before) + + def test_a_customised_passage_is_skipped_and_the_others_change(self) -> None: + install = self.put(MIGRATION.INSTALL_DOC, b"# Install our app\n\nOur own text.\n") + text = old(MIGRATION.INSTALL_DOC).decode("utf-8").replace("is listed in Napari, and not in Fiji", "is listed in Napari only, not in Fiji") + log = self.run_migration() + self.assertIn(f"{MIGRATION.INSTALL_DOC}: SKIPPED: customised", log) + self.assertEqual(install.read_bytes(), b"# Install our app\n\nOur own text.\n") + install.write_text(text, encoding="utf-8", newline="\n") + log = self.run_migration() + self.assertIn(f"{MIGRATION.INSTALL_DOC}: updated: 2 text change(s); SKIPPED 1 passage(s)", log) + changed = lf(install) + self.assertIn("is listed in Napari only, not in Fiji", changed) + self.assertIn(f"]({SITE}guides/image-software/)", changed) + self.assertIn(f"{MIGRATION.INSTALL_DOC}: unchanged: the other changes are there; SKIPPED 1 passage(s)", self.run_migration()) + + def test_missing_files_are_not_created(self) -> None: + for relative in MIGRATION.FILES: + (self.repo / relative).unlink() + log = self.run_migration() + for relative in MIGRATION.FILES: + self.assertIn(f"{relative}: not present in this repository (nothing was created)", log) + self.assertEqual([p for p in self.repo.rglob("*") if p.is_file()], []) + + def test_a_file_that_is_not_text_is_skipped(self) -> None: + self.put(MIGRATION.TOOLS_DOC, b"\xff\xfe not utf-8") + log = self.run_migration() + self.assertIn(f"{MIGRATION.TOOLS_DOC}: SKIPPED", log) + self.assertEqual((self.repo / MIGRATION.TOOLS_DOC).read_bytes(), b"\xff\xfe not utf-8") + + def test_the_sync_script_runs_the_migration_from_0_1_31(self) -> None: + shutil.copytree(ROOT / ".template_sync", self.repo / ".template_sync") + # sync.py refuses a target other than the manifest version: pin the copy to 0.1.32 (later templates add migrations). + manifest = self.repo / ".template_sync/manifest.yaml" + manifest.write_text(re.sub(r"template_version: [0-9.]+", "template_version: 0.1.32", manifest.read_text(encoding="utf-8")), encoding="utf-8") + command = [sys.executable, str(self.repo / ".template_sync/sync.py"), "--from-version", "0.1.31", "--to-version", "0.1.32", "--repository-root", str(self.repo)] + env = {key: value for key, value in os.environ.items() if key != "PYTHONPATH"} + result = subprocess.run(command, capture_output=True, text=True, env=env, check=False) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("[migration 0.1.32]", result.stdout) + self.assertEqual((self.repo / MIGRATION.TOOLS_DOC).read_bytes(), (ROOT / MIGRATION.TOOLS_DOC).read_bytes()) + again = subprocess.run(command, capture_output=True, text=True, env=env, check=False) + self.assertIn("no repository changes were required", again.stdout) + + +if __name__ == "__main__": + unittest.main()