From c8ed2ca06b7a9cb91955cdaa42cee3d9e388f906 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 24 Aug 2026 19:39:41 +0000 Subject: [PATCH] docs: complete the canonical arcticpy install note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both autocti_workspace/AGENTS.md and autocti_workspace_test/AGENTS.md cite this section as the canonical arcticpy note, and it was the least complete of the three: it said "install it after numpy is in place" and then the bare `pip install arcticpy` line, omitting Cython, setuptools, scipy and matplotlib. A first-time user following it verbatim on a clean modern venv cannot get arcticpy installed. Each gap was reproduced against a clean build of arcticpy 2.6: - setuptools/wheel — --no-build-isolation does not read arcticpy's build-system.requires, so build deps must already be present. Without setuptools: `BackendUnavailable: Cannot import 'setuptools.build_meta'`. Python 3.12+ venvs no longer ship setuptools by default. - scipy/matplotlib — --no-deps suppresses arcticpy's runtime dependencies, but arcticpy/__init__.py imports read_noise, which imports both at import time. A successful build still fails at `import arcticpy` without them. - The verification command — arcticpy exposes no __version__ attribute, so `print(arcticpy.__version__)` raises AttributeError on a healthy install. Documented via importlib.metadata instead. Also points at PyAutoHeart/.github/actions/install-arcticpy as the single owner of this recipe and of the arcticpy==2.6 pin, so the note and the CI that every CTI repo actually runs cannot drift apart again. Refs PyAutoLabs/PyAutoHeart#170 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_018nDAxBEavkzb6Zkz1cYHef --- AGENTS.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 1dfe0192..093ab535 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,12 +40,43 @@ a pip dependency: toolchain to build. - Its own requirements **downgrade numpy below 2.0**, breaking a modern stack. -Install it after numpy is in place: +So it is built with `--no-build-isolation` (reusing the numpy already present) +and `--no-deps` (so it cannot drag numpy back down). Both flags have to be paid +back by hand, and this is where installs go wrong: + +- `--no-build-isolation` means pip does **not** read arcticpy's + `build-system.requires`, so every **build** dependency must already be + installed. arcticpy declares none. Without `setuptools` the build fails with + `BackendUnavailable: Cannot import 'setuptools.build_meta'` — and Python + 3.12+ venvs no longer ship setuptools by default. +- `--no-deps` means pip installs no **runtime** dependencies either. + `arcticpy/__init__.py` imports `read_noise`, which imports `scipy` and + `matplotlib` at import time, so without them a successful build still fails + at `import arcticpy` with `ModuleNotFoundError`. + +The full recipe: ```bash +sudo apt-get update && sudo apt-get install -y libgsl-dev +pip install --upgrade pip setuptools wheel # BUILD deps: --no-build-isolation +pip install numpy cython # will not supply these +pip install scipy matplotlib # RUNTIME deps --no-deps suppresses pip install arcticpy==2.6 --no-build-isolation --no-deps ``` +Verify with the distribution metadata, **not** `arcticpy.__version__` — +arcticpy exposes no such attribute, so that raises `AttributeError` even on a +healthy install: + +```bash +python -c "import arcticpy; from importlib.metadata import version; print(version('arcticpy'))" +``` + +This recipe has one owner for the whole organism: +**`PyAutoHeart/.github/actions/install-arcticpy`**, the composite action every +CTI repo's CI consumes. It also holds the single `arcticpy==2.6` pin — bump it +there, not here. Keep this note and that action in step. + If GSL headers are missing and you lack root, extract them locally (`apt-get download libgsl-dev && dpkg -x ...`) and point `CPPFLAGS`/`LDFLAGS` at them.