I read this plugin line by line as well — see
the Sigil thread for the long version, since most of what I found applies to both and most of it was our documentation's fault rather than the plugin's.
The short version, all now documented in INTEGRATING.md:
- -u decides what the JSON contains. With "show usage messages" off, the summary row at the bottom reports 0 usages — true about the output, false about the book. Pass -u always and let the preference decide what the dock draws.
- tool_version is in the envelope, so installed_epubveri_version() need not launch a second process to read epubveri -V.
- Prefer musl on Linux over unknown-linux-gnu: static, and runs on distributions where the gnu build will not start.
- data.advisory_basis separates NEXT-* (becomes a real error once epubcheck catches up) from ADV-* (never will), if you ever want to show them differently.
- Exit code 2 still carries a full report — for a missing file or a directory the JSON on stdout holds the explanation and stderr is empty, so the "epubveri was unable to validate the book" dialog currently shows raw JSON as its detail. Parsing stdout first handles both.
- Verifying the download against the release's SHA256SUMS.txt is about twenty lines; the doc has the recipe, and is honest about the modest thing it buys.
One hygiene note. The archive is opened with extractall(), which Python 3.14 changes the default filtering for and which is the classic path-traversal shape. Sigil's plugin extracts a single named member instead, which is the safer pattern of the two.
And credit where it is due, since the Sigil post named places where this plugin is the better of the two: timeouts on every request, draft and prerelease filtering, falling back to the installed binary when GitHub is unreachable, and the clipboard write that verifies and retries. That last one is not obvious knowledge.