Generalize the CLI-bridge rationale to any host, and say why Python needs it too

[stevevanhooser]

README only (+67/−13). No code changes.

Why

"Why a CLI bridge?" was written when MATLAB was the only host, so it reads as a list of MATLAB workarounds — interpreter isolation from MATLAB's memory space, raw binary so MATLAB can typecast it. That framing invites a Python caller to conclude the subprocess is pure overhead and reach for import sonpy directly.

Usually that doesn't work, and the reasons belong in this section rather than being rediscovered.

This came up while planning NDR-python's .smrx support: the first instinct was "import sonpy, the CLI is a MATLAB artifact," and it took reading install.sh and the PyPI metadata to see why that's wrong.

What changed

• Generalized the existing points from MATLAB to any host.
• Split crash containment out of interpreter isolation. It's a separate and stronger argument: a sonpy abort() takes down whatever process it's in, Python included.
• New subsection, "Why a Python host wants the bridge too" — what is actually installable, and why the subprocess is the only mechanism on some platforms.
• Noted the sentinel check is the host's job, not MATLAB's. subprocess.returncode has the identical blind spot when the arch -x86_64 wrapper masks a signal death, so a Python host that skips it gets silently truncated data in exactly the case the sentinel exists to catch.
• Fixed the intro and the troubleshooting section, both of which described that check as MATLAB's responsibility.

The constraint is tighter than the Apple Silicon note alone suggests

Current release (1.9.12):

Platform	Wheels
Linux x86_64 (manylinux_2_39)	CPython 3.14 only
macOS (universal2)	CPython 3.14 only
Windows x86_64	CPython 3.9 – 3.14
Linux aarch64	none

The part I hadn't expected: older releases don't fill the gaps. Each is pinned by Requires-Python to exactly one minor version — 1.7.x→3.7, 1.8.x→3.8, 1.9.1–1.9.5→3.9. Their py3-none-any wheel tag looks permissive but isn't.

So on Linux and macOS, pip install sonpy on CPython 3.10–3.13 fails outright rather than resolving to something older. Not "falls back to an old version" — no candidate at all.

Verification

Claims were checked against primary sources, not memory:

• Wheel matrix and per-release Requires-Python read from the PyPI JSON metadata for all 14 releases.
• The install failure reproduced on CPython 3.11 / Linux x86_64 in a clean venv — pip lists every version it rejected and finds nothing.
• Apple Silicon behaviour taken from this repo's own install.sh (the arch -x86_64 wrapper at lines 208–214, and its comment on why it's a wrapper rather than a symlink).
• All in-page anchors resolve to real headings; code fences balanced.

One correction worth recording: an early import test appeared to succeed on 3.11. It was picking up a stray sonpy/ download directory as an implicit namespace package — sonpy.__file__ was None and from sonpy import lib failed. Re-run from a clean working directory, the import fails properly. Nothing from that false positive reached the text.

---

Generated by Claude Code