From 24debfa7546588d25828d35b30c866df7454a59e Mon Sep 17 00:00:00 2001 From: Dusten Hubbard Date: Tue, 21 Jul 2026 14:21:07 -0500 Subject: [PATCH] docs: uv-first source install, Python 3.11 stated up front The maintainer hit `pip install -e .` failing on a Mac with Python 3.14 because the project pins `>=3.11,<3.12`. State the Python 3.11 requirement before the venv step in every source-install block, and recommend uv (which auto-downloads 3.11) with plain venv as the alternative for those who already have python3.11. - README.md "From source (developers)": 3.11 up front; uv-first block with venv alternative; note to rerun the editable install only when pyproject.toml changes. - docs/USER_GUIDE.md "From source (Linux, other platforms, and developers)": same treatment for both the quick git+ install and the track-main editable clone; Windows activation note. - CONTRIBUTING.md: mention `uv pip install -e .` alongside `pip install -e .`. Co-Authored-By: Claude Fable 5 --- CONTRIBUTING.md | 5 +++-- README.md | 25 ++++++++++++++++++++----- docs/USER_GUIDE.md | 30 +++++++++++++++++++++++++----- 3 files changed, 48 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 714badc6..5c9fb092 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,8 +83,9 @@ In the activated environment, run the app from the repository root: python PyReconstruct/run.py ``` -Alternatively, `pip install -e .` installs the package in editable mode and -provides the `PyReconstruct` console command (the entry point declared in +Alternatively, `pip install -e .` (or `uv pip install -e .` in a Python 3.11 +`uv venv` — see [docs/DEV_UV.md](docs/DEV_UV.md)) installs the package in editable +mode and provides the `PyReconstruct` console command (the entry point declared in `pyproject.toml`, `PyReconstruct.cli:main`). --- diff --git a/README.md b/README.md index 05f0915e..46df53e3 100644 --- a/README.md +++ b/README.md @@ -62,18 +62,33 @@ default. ### From source (developers) To track the latest commits on `main` (this replaces the old in-app "Developer" -update channel), run a source install rather than a frozen build. In a Python -3.11 environment — a `venv` or a conda env (the project pins `>=3.11,<3.12`): +update channel), run a source install rather than a frozen build. + +PyReconstruct requires **Python 3.11** — the pinned version the app and its +native dependencies are validated on (the project pins `>=3.11,<3.12`). Your +system `python3` is likely newer, and `pip install -e .` will fail against it; the +steps below get you 3.11 without changing your system Python. ``` git clone https://github.com/dustenhubbard/PyReconstruct cd PyReconstruct -pip install -e . # editable: your working tree IS the running code -PyReconstruct + +# recommended: uv (installs Python 3.11 for you) +curl -LsSf https://astral.sh/uv/install.sh | sh # or: brew install uv +uv venv --python 3.11 +source .venv/bin/activate # Windows: .venv\Scripts\activate +uv pip install -e . # editable: your working tree IS the running code + +# alternative: plain venv (requires python3.11 already on PATH) +python3.11 -m venv .venv && source .venv/bin/activate +pip install -e . + +PyReconstruct # launch ``` Pull to move to the newest code (`git pull`); because the install is editable, -the pulled source runs immediately with no reinstall. You can also update from +the pulled source runs immediately with no reinstall — rerun the editable install +only when `pyproject.toml` changes. You can also update from inside the app — **Help ▸ Check for updates** on a source install reinstalls the branch set under **Series ▸ Options ▸ Updates** (default `main`) with `pip` — or from the command line with `PyReconstruct --update` (`PyReconstruct --switch diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 9127e4fc..54aa3457 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -89,15 +89,25 @@ Mac its matching architecture. ### From source (Linux, other platforms, and developers) -In a Python 3.11 environment (the project pins `>=3.11,<3.12`): +PyReconstruct requires **Python 3.11** — the pinned version the app and its +native dependencies are validated on (the project pins `>=3.11,<3.12`). Your +system `python3` is likely newer, and installing against it will fail; the steps +below get you 3.11 without changing your system Python. The recommended tool is +[uv](https://docs.astral.sh/uv/), which downloads Python 3.11 for you — install +it with `curl -LsSf https://astral.sh/uv/install.sh | sh` (or `brew install uv`). + +For a quick, non-editable install into a fresh 3.11 environment: ``` -pip install git+https://github.com/dustenhubbard/PyReconstruct +uv venv --python 3.11 && source .venv/bin/activate # Windows: .venv\Scripts\activate +uv pip install git+https://github.com/dustenhubbard/PyReconstruct PyReconstruct ``` `pip` pulls in the runtime dependencies (PySide6, VTK, vedo, NumPy, SciPy, -scikit-image, shapely, trimesh, zarr, and others). +scikit-image, shapely, trimesh, zarr, and others). If you already have +`python3.11` on PATH, plain `venv` works instead of `uv`: `python3.11 -m venv +.venv && source .venv/bin/activate`, then `pip install git+…`. To **track the latest unreleased code on `main`** (what the retired in-app "Developer" channel used to offer), clone the repository and install it editable, @@ -106,8 +116,18 @@ then `git pull` whenever you want the newest commits: ``` git clone https://github.com/dustenhubbard/PyReconstruct cd PyReconstruct -pip install -e . # editable: the checkout IS the running code -git pull # later, to move to the newest main; no reinstall needed + +# recommended: uv (installs Python 3.11 for you) +uv venv --python 3.11 +source .venv/bin/activate # Windows: .venv\Scripts\activate +uv pip install -e . # editable: the checkout IS the running code + +# alternative: plain venv (requires python3.11 already on PATH) +python3.11 -m venv .venv && source .venv/bin/activate +pip install -e . + +git pull # later, to move to the newest main; rerun the + # editable install only when pyproject.toml changes ``` For a full development setup (the conda `pyrecon_dev` environment, tests, code